bump version to 1.1.14-1

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

.gitignore

@@ -1,5 +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,11 +1,21 @@
 [package]
 name = "proxmox-backup"
-version = "0.2.3"
+version = "1.1.14"
-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"
 homepage = "https://www.proxmox.com"
+build = "build.rs"
 
 exclude = [ "build", "debian", "tests/catar_data/test_symlink/symlink1"]
 
@@ -14,48 +24,69 @@ name = "proxmox_backup"
 path = "src/lib.rs"
 
 [dependencies]
+apt-pkg-native = "0.3.2"
 base64 = "0.12"
 bitflags = "1.2.1"
-bytes = "0.5"
+bytes = "1.0"
-chrono = "0.4" # Date and time library for Rust
 crc32fast = "1"
 endian_trait = { version = "0.6", features = ["arrays"] }
+env_logger = "0.7"
+flate2 = "1.0"
 anyhow = "1.0"
+foreign-types = "0.3"
+thiserror = "1.0"
 futures = "0.3"
-h2 = { version = "0.2", features = ["stream"] }
+h2 = { version = "0.3", features = [ "stream" ] }
 handlebars = "3.0"
 http = "0.2"
-hyper = "0.13"
+hyper = { version = "0.14", features = [ "full" ] }
 lazy_static = "1.4"
 libc = "0.2"
 log = "0.4"
-nix = "0.16"
+nix = "0.19.1"
+num-traits = "0.2"
 once_cell = "1.3.1"
 openssl = "0.10"
 pam = "0.7"
 pam-sys = "0.5"
 percent-encoding = "2.1"
 pin-utils = "0.1.0"
-proxmox = { version = "0.1.38", features = [ "sortable-macro", "api-macro" ] }
+pin-project = "1.0"
-#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" ] }
 regex = "1.2"
-rustyline = "6"
+rustyline = "7"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 siphasher = "0.3"
 syslog = "4.0"
-tokio = { version = "0.2.9", features = [ "blocking", "fs", "io-util", "macros", "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.6", features = [ "codec", "io" ] }
 tower-service = "0.3.0"
-udev = "0.3"
+udev = ">= 0.3, <0.5"
 url = "2.1"
 #valgrind_request = { git = "https://github.com/edef1c/libvalgrind_request", version = "1.1.0", optional = true }
 walkdir = "2"
+webauthn-rs = "0.2.5"
 xdg = "2.2"
 zstd = { version = "0.4", features = [ "bindgen" ] }
 nom = "5.1"
+crossbeam-channel = "0.5"
+
+pathpatterns = "0.1.2"
+pxar = { version = "0.10.1", features = [ "tokio-io" ] }
+
+proxmox = { version = "0.11.6", features = [ "sortable-macro", "api-macro", "cli", "router", "tfa" ] }
+proxmox-acme-rs = "0.3"
+proxmox-fuse = "0.1.1"
+proxmox-http = { version = "0.2.1", features = [ "client", "http-helpers", "websocket" ] }
+
+# Local path overrides
+# NOTE: You must run `cargo update` after changing this for it to take effect!
+[patch.crates-io]
+#proxmox = { path = "../proxmox/proxmox", features = [ "sortable-macro", "api-macro", "cli", "router", "tfa" ] }
+#proxmox-http = { path = "../proxmox/proxmox-http", features = [ "client", "http-helpers", "websocket" ] }
+#pxar = { path = "../pxar", features = [ "tokio-io" ] }
 
 [features]
 default = []

Makefile

@@ -9,7 +9,11 @@ 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 := \
@@ -19,7 +23,12 @@ USR_SBIN := \
 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
 
 ifeq ($(BUILD_MODE), release)
 CARGO_BUILD_ARGS += --release
@@ -35,13 +44,20 @@ 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
 
 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} ${CLIENT_DEB}
+DEBS=${SERVER_DEB} ${SERVER_DBG_DEB} ${CLIENT_DEB} ${CLIENT_DBG_DEB} \
+     ${RESTORE_DEB} ${RESTORE_DBG_DEB}
 
 DSC = rust-${PACKAGE}_${DEB_VERSION}.dsc
 
@@ -65,10 +81,18 @@ doc:
 .PHONY: build
 build:
 	rm -rf 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/-.*//')
+	rm -f debian/control
+	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/-.*//')
 	sed -e '1,/^$$/ ! d' build/debian/control > build/debian/control.src
 	cat build/debian/control.src build/debian/control.in > build/debian/control
 	rm build/debian/control.in build/debian/control.src
+	cp build/debian/control debian/control
 	rm build/Cargo.lock
 	find build/debian -name "*.hint" -delete
 	$(foreach i,$(SUBDIRS), \
@@ -76,18 +100,23 @@ build:
 
 
 .PHONY: proxmox-backup-docs
-proxmox-backup-docs: $(DOC_DEB)
+$(DOC_DEB) $(DEBS): proxmox-backup-docs
-$(DOC_DEB): build
+proxmox-backup-docs: build
 	cd build; dpkg-buildpackage -b -us -uc --no-pre-clean
 	lintian $(DOC_DEB)
 
 # copy the local target/ dir as a build-cache
 .PHONY: deb
-deb: $(DEBS)
+$(DEBS): deb
-$(DEBS): build
+deb: build
 	cd build; dpkg-buildpackage -b -us -uc --no-pre-clean --build-profiles=nodoc
 	lintian $(DEBS)
 
+.PHONY: deb-all
+deb-all: build
+	cd build; dpkg-buildpackage -b -us -uc --no-pre-clean
+	lintian $(DEBS) $(DOC_DEB)
+
 .PHONY: dsc
 dsc: $(DSC)
 $(DSC): build
@@ -104,8 +133,8 @@ clean:
 	find . -name '*~' -exec rm {} ';'
 
 .PHONY: dinstall
-dinstall: ${DEBS}
+dinstall: ${SERVER_DEB} ${SERVER_DBG_DEB} ${CLIENT_DEB} ${CLIENT_DBG_DEB}
-	dpkg -i ${DEBS}
+	dpkg -i $^
 
 # make sure we build binaries before docs
 docs: cargo-build
@@ -131,14 +160,21 @@ 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}
 	# check if working directory is clean
 	git diff --exit-code --stat && git diff --exit-code --stat --staged
-	tar cf - ${SERVER_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} ${CLIENT_DBG_DEB} | \
-	tar cf - ${CLIENT_DEB} | ssh -X repoman@repo.proxmox.com upload --product "pbs,pve" --dist buster
+	    ssh -X repoman@repo.proxmox.com upload --product pbs --dist buster
+	tar cf - ${CLIENT_DEB} ${CLIENT_DBG_DEB} | ssh -X repoman@repo.proxmox.com upload --product "pve,pmg,pbs-client" --dist buster
+	tar cf - ${RESTORE_DEB} ${RESTORE_DBG_DEB} | ssh -X repoman@repo.proxmox.com upload --product "pve" --dist buster

README.rst

@@ -13,7 +13,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 +22,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 +36,100 @@ 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 Buster
+
+Setup:
+  1. # echo 'deb http://download.proxmox.com/debian/devel/ buster main' >> /etc/apt/sources.list.d/proxmox-devel.list
+  2. # sudo wget http://download.proxmox.com/debian/proxmox-ve-release-6.x.gpg -O /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
+  3. # sudo apt update
+  4. # sudo apt install devscripts debcargo clang
+  5. # git clone git://git.proxmox.com/git/proxmox-backup.git
+  6. # 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.
+
+
+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 start location
+- read the chunk data
+- seek to the first chunk 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

@@ -30,10 +30,9 @@ Chores:
 
 * move tools/xattr.rs and tools/acl.rs to proxmox/sys/linux/
 
-* recompute PXAR_ header types from strings: avoid using numbers from casync
-
 * remove pbs-* systemd timers and services on package purge
 
 
 Suggestions
 ===========
+

build.rs

@@ -0,0 +1,23 @@
+// build.rs
+use std::env;
+use std::process::Command;
+
+fn git_command(args: &[&str]) -> String {
+    match Command::new("git").args(args).output() {
+        Ok(output) => String::from_utf8(output.stdout).unwrap().trim_end().to_string(),
+        Err(err) => {
+            panic!("git {:?} failed: {}", args, err);
+        }
+    }
+}
+
+fn main() {
+    let repo_path = git_command(&["rev-parse", "--show-toplevel"]);
+    let repoid = match env::var("REPOID") {
+        Ok(repoid) => repoid,
+        Err(_) => git_command(&["rev-parse", "HEAD"]),
+    };
+
+    println!("cargo:rustc-env=REPOID={}", repoid);
+    println!("cargo:rerun-if-changed={}/.git/HEAD", repo_path);
+}

debian/control

@@ -0,0 +1,171 @@
+Source: rust-proxmox-backup
+Section: admin
+Priority: optional
+Build-Depends: debhelper (>= 11),
+ dh-cargo (>= 18),
+ cargo:native,
+ rustc:native,
+ libstd-rust-dev,
+ librust-anyhow-1+default-dev,
+ librust-apt-pkg-native-0.3+default-dev (>= 0.3.2-~~),
+ librust-base64-0.12+default-dev,
+ librust-bitflags-1+default-dev (>= 1.2.1-~~),
+ librust-bytes-1+default-dev,
+ 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.7+default-dev,
+ librust-flate2-1+default-dev,
+ librust-foreign-types-0.3+default-dev,
+ librust-futures-0.3+default-dev,
+ librust-h2-0.3+default-dev,
+ librust-h2-0.3+stream-dev,
+ librust-handlebars-3+default-dev,
+ librust-http-0.2+default-dev,
+ librust-hyper-0.14+default-dev,
+ librust-hyper-0.14+full-dev,
+ librust-lazy-static-1+default-dev (>= 1.4-~~),
+ librust-libc-0.2+default-dev,
+ librust-log-0.4+default-dev,
+ librust-nix-0.19+default-dev (>= 0.19.1-~~),
+ 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-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-project-1+default-dev,
+ librust-pin-utils-0.1+default-dev,
+ librust-proxmox-0.11+api-macro-dev (>= 0.11.6-~~),
+ librust-proxmox-0.11+cli-dev (>= 0.11.6-~~),
+ librust-proxmox-0.11+default-dev (>= 0.11.6-~~),
+ librust-proxmox-0.11+router-dev (>= 0.11.6-~~),
+ librust-proxmox-0.11+sortable-macro-dev (>= 0.11.6-~~),
+ librust-proxmox-0.11+tfa-dev (>= 0.11.6-~~),
+ librust-proxmox-acme-rs-0.3+default-dev,
+ librust-proxmox-fuse-0.1+default-dev (>= 0.1.1-~~),
+ librust-proxmox-http-0.2+client-dev (>= 0.2.1-~~),
+ librust-proxmox-http-0.2+default-dev (>= 0.2.1-~~),
+ librust-proxmox-http-0.2+http-helpers-dev (>= 0.2.1-~~),
+ librust-proxmox-http-0.2+websocket-dev (>= 0.2.1-~~),
+ 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.2-~~),
+ librust-rustyline-7+default-dev,
+ librust-serde-1+default-dev,
+ librust-serde-1+derive-dev,
+ librust-serde-json-1+default-dev,
+ librust-siphasher-0.3+default-dev,
+ librust-syslog-4+default-dev,
+ librust-thiserror-1+default-dev,
+ librust-tokio-1+default-dev (>= 1.6-~~),
+ librust-tokio-1+fs-dev (>= 1.6-~~),
+ librust-tokio-1+io-std-dev (>= 1.6-~~),
+ librust-tokio-1+io-util-dev (>= 1.6-~~),
+ librust-tokio-1+macros-dev (>= 1.6-~~),
+ librust-tokio-1+net-dev (>= 1.6-~~),
+ librust-tokio-1+parking-lot-dev (>= 1.6-~~),
+ librust-tokio-1+process-dev (>= 1.6-~~),
+ librust-tokio-1+rt-dev (>= 1.6-~~),
+ librust-tokio-1+rt-multi-thread-dev (>= 1.6-~~),
+ librust-tokio-1+signal-dev (>= 1.6-~~),
+ librust-tokio-1+time-dev (>= 1.6-~~),
+ librust-tokio-openssl-0.6+default-dev (>= 0.6.1-~~),
+ librust-tokio-stream-0.1+default-dev,
+ librust-tokio-util-0.6+codec-dev,
+ librust-tokio-util-0.6+default-dev,
+ librust-tokio-util-0.6+io-dev,
+ librust-tower-service-0.3+default-dev,
+ librust-udev-0.4+default-dev | librust-udev-0.3+default-dev,
+ librust-url-2+default-dev (>= 2.1-~~),
+ librust-walkdir-2+default-dev,
+ librust-webauthn-rs-0.2+default-dev (>= 0.2.5-~~),
+ librust-xdg-2+default-dev (>= 2.2-~~),
+ librust-zstd-0.4+bindgen-dev,
+ librust-zstd-0.4+default-dev,
+ libacl1-dev,
+ libfuse3-dev,
+ libsystemd-dev,
+ uuid-dev,
+ libsgutils2-dev,
+ bash-completion,
+ debhelper (>= 12~),
+ fonts-dejavu-core <!nodoc>,
+ fonts-lato <!nodoc>,
+ fonts-open-sans <!nodoc>,
+ graphviz <!nodoc>,
+ latexmk <!nodoc>,
+ patchelf,
+ 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
+Vcs-Git: git://git.proxmox.com/git/proxmox-backup.git
+Vcs-Browser: https://git.proxmox.com/?p=proxmox-backup.git;a=summary
+Homepage: https://www.proxmox.com
+
+Package: proxmox-backup-server
+Architecture: any
+Depends: fonts-font-awesome,
+         libjs-extjs (>= 6.0.1),
+         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.6-2),
+         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: 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.
+
+Package: proxmox-backup-docs
+Build-Profiles: <!nodoc>
+Section: doc
+Depends: 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,
+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

@@ -2,19 +2,33 @@ Package: proxmox-backup-server
 Architecture: any
 Depends: fonts-font-awesome,
          libjs-extjs (>= 6.0.1),
+         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 (>= 2.6-2),
+         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.
@@ -23,7 +37,19 @@ Package: proxmox-backup-docs
 Build-Profiles: <!nodoc>
 Section: doc
 Depends: 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,
+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/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

@@ -2,32 +2,32 @@ overlay = "."
 crate_src_path = ".."
 whitelist = ["tests/*.c"]
 
-# needed for pinutils alpha
+maintainer = "Proxmox Support Team <support@proxmox.com>"
-allow_prerelease_deps = true
 
 [source]
-# TODO: update once public
+vcs_git = "git://git.proxmox.com/git/proxmox-backup.git"
-vcs_git = ""
+vcs_browser = "https://git.proxmox.com/?p=proxmox-backup.git;a=summary"
-vcs_browser = ""
-maintainer = "Proxmox Support Team <support@proxmox.com>"
 section = "admin"
 build_depends = [
-  "debhelper (>= 12~)",
   "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",
+  "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>",
 ]
+
 build_depends_excludes = [
   "debhelper (>=11)",
 ]
@@ -38,4 +38,5 @@ depends = [
   "libfuse3-dev",
   "libsystemd-dev",
   "uuid-dev",
+  "libsgutils2-dev",
 ]

debian/lintian-overrides

@@ -0,0 +1,2 @@
+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

@@ -0,0 +1,83 @@
+#!/bin/sh
+
+set -e
+
+#DEBHELPER#
+
+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
+
+	# FIXME: Remove with 1.1
+	if test -n "$2"; then
+		if dpkg --compare-versions "$2" 'lt' '0.9.4-1'; then
+			if grep -s -q  -P -e '^\s+verify-schedule ' /etc/proxmox-backup/datastore.cfg; then
+				echo "NOTE: drop all verify schedules from datastore config."
+				echo "You can now add more flexible verify jobs"
+				flock -w 30 /etc/proxmox-backup/.datastore.lck \
+				    sed -i '/^\s\+verify-schedule /d' /etc/proxmox-backup/datastore.cfg || true
+			fi
+		fi
+		if dpkg --compare-versions "$2" 'le' '0.9.5-1'; then
+			chown --quiet backup:backup /var/log/proxmox-backup/api/auth.log || true
+		fi
+		if dpkg --compare-versions "$2" 'le' '0.9.7-1'; then
+			if [ -e /etc/proxmox-backup/remote.cfg ]; then
+				echo "NOTE: Switching over remote.cfg to new field names.."
+				flock -w 30 /etc/proxmox-backup/.remote.lck \
+				    sed -i \
+				        -e 's/^\s\+userid /\tauth-id /g' \
+				        /etc/proxmox-backup/remote.cfg || true
+			fi
+		fi
+		if dpkg --compare-versions "$2" 'le' '1.0.14-1'; then
+			# FIXME: Remove with 2.0
+			if grep -s -q  -P -e '^linux:' /etc/proxmox-backup/tape.cfg; then
+				echo "========="
+				echo "= NOTE: You have now unsupported 'linux' tape drives configured."
+				echo "= * Execute 'udevadm control --reload-rules && udevadm trigger' to update /dev"
+				echo "= * Edit '/etc/proxmox-backup/tape.cfg', remove 'linux' entries and re-add over CLI/GUI"
+				echo "========="
+			fi
+		fi
+		# FIXME: remove with 2.0
+		if [ -d "/var/lib/proxmox-backup/tape" ] &&
+		   [ "$(stat --printf '%a' '/var/lib/proxmox-backup/tape')" != "750" ]; then
+			chmod 0750 /var/lib/proxmox-backup/tape || true
+		fi
+		# 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
+	fi
+    ;;
+
+    abort-upgrade|abort-remove|abort-deconfigure)
+    ;;
+
+    *)
+        echo "postinst called with unknown argument \`$1'" >&2
+        exit 1
+    ;;
+esac
+
+exit 0

debian/prerm

@@ -0,0 +1,11 @@
+#!/bin/sh
+
+set -e
+
+#DEBHELPER#
+
+# 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' 'proxmox-backup-daily-update.timer' >/dev/null || true
+fi

debian/proxmox-backup-docs.links

@@ -0,0 +1,5 @@
+/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/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,4 @@
 debian/proxmox-backup-manager.bc proxmox-backup-manager
+debian/proxmox-tape.bc proxmox-tape
+debian/pmtx.bc pmtx
+debian/pmt.bc pmt

debian/proxmox-backup-server.install

@@ -1,15 +1,37 @@
 etc/proxmox-backup-proxy.service /lib/systemd/system/
 etc/proxmox-backup.service /lib/systemd/system/
 etc/proxmox-backup-banner.service /lib/systemd/system/
+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-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-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-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

@@ -37,11 +37,28 @@ override_dh_auto_install:
 	    PROXY_USER=backup \
 	    LIBDIR=/usr/lib/$(DEB_HOST_MULTIARCH)
 
-override_dh_installinit:
+override_dh_installsystemd:
-	dh_installinit
+	dh_installsystemd -pproxmox-backup-server  proxmox-backup-daily-update.timer
-	dh_installinit --name proxmox-backup-proxy
+	# note: we start/try-reload-restart services manually in postinst
+	dh_installsystemd --no-start --no-restart-after-upgrade
+
+override_dh_fixperms:
+	dh_fixperms --exclude sg-tape-cmd
 
 # workaround https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=933541
 # TODO: remove once available (Debian 11 ?)
 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,43 +1,85 @@
 include ../defines.mk
 
-ifeq ($(BUILD_MODE), release)
-COMPILEDIR := ../target/release
-else
-COMPILEDIR := ../target/debug
-endif
-
 GENERATED_SYNOPSIS := 						\
+	proxmox-tape/synopsis.rst				\
 	proxmox-backup-client/synopsis.rst			\
 	proxmox-backup-client/catalog-shell-synopsis.rst 	\
 	proxmox-backup-manager/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
 
+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
+
+LTO_BARCODE_FILES :=						\
+	lto-barcode/index.html					\
+	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
+
+API_VIEWER_SOURCES=				\
+	api-viewer/index.html			\
+	api-viewer/apidoc.js
 
 # Sphinx documentation setup
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 BUILDDIR      = output
 
+ifeq ($(BUILD_MODE), release)
+COMPILEDIR := ../target/release
+SPHINXOPTS    += -t release
+else
+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
 
@@ -47,6 +89,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
 
@@ -65,9 +181,34 @@ 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 $< >$@
+
+.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/apidata.js api-viewer/PBSAPI.js
+	cat api-viewer/apidata.js api-viewer/PBSAPI.js >$@
+
 .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."
 
@@ -86,12 +227,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
 
 
-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/PBSAPI.js

@@ -0,0 +1,526 @@
+// avoid errors when running without development tools
+if (!Ext.isDefined(Ext.global.console)) {
+    var console = {
+        dir: function() {},
+        log: function() {}
+    };
+}
+
+Ext.onReady(function() {
+
+    Ext.define('pve-param-schema', {
+        extend: 'Ext.data.Model',
+        fields:  [
+	    'name', 'type', 'typetext', 'description', 'verbose_description',
+	    'enum', 'minimum', 'maximum', 'minLength', 'maxLength',
+	    'pattern', 'title', 'requires', 'format', 'default',
+	    'disallow', 'extends', 'links',
+	    {
+		name: 'optional',
+		type: 'boolean'
+	    }
+	]
+    });
+
+    var store = Ext.define('pve-updated-treestore', {
+	extend: 'Ext.data.TreeStore',
+	model: Ext.define('pve-api-doc', {
+            extend: 'Ext.data.Model',
+            fields:  [
+		'path', 'info', 'text',
+	    ]
+	}),
+        proxy: {
+            type: 'memory',
+            data: pbsapi
+        },
+        sorters: [{
+            property: 'leaf',
+            direction: 'ASC'
+        }, {
+            property: 'text',
+            direction: 'ASC'
+	}],
+	filterer: 'bottomup',
+	doFilter: function(node) {
+	    this.filterNodes(node, this.getFilters().getFilterFn(), true);
+	},
+
+	filterNodes: function(node, filterFn, parentVisible) {
+	    var me = this,
+		bottomUpFiltering = me.filterer === 'bottomup',
+		match = filterFn(node) && parentVisible || (node.isRoot() && !me.getRootVisible()),
+		childNodes = node.childNodes,
+		len = childNodes && childNodes.length, i, matchingChildren;
+
+	    if (len) {
+		for (i = 0; i < len; ++i) {
+		    matchingChildren = me.filterNodes(childNodes[i], filterFn, match || bottomUpFiltering) || matchingChildren;
+		}
+		if (bottomUpFiltering) {
+		    match = matchingChildren || match;
+		}
+	    }
+
+	    node.set("visible", match, me._silentOptions);
+	    return match;
+	},
+
+    }).create();
+
+    var render_description = function(value, metaData, record) {
+	var pdef = record.data;
+
+	value = pdef.verbose_description || value;
+
+	// TODO: try to render asciidoc correctly
+
+	metaData.style = 'white-space:pre-wrap;'
+
+	return Ext.htmlEncode(value);
+    };
+
+    var render_type = function(value, metaData, record) {
+	var pdef = record.data;
+
+	return pdef['enum'] ? 'enum' : (pdef.type || 'string');
+    };
+
+    let render_simple_format = function(pdef, type_fallback) {
+	if (pdef.typetext)
+	    return pdef.typetext;
+
+	if (pdef['enum'])
+	    return pdef['enum'].join(' | ');
+
+	if (pdef.format)
+	    return pdef.format;
+
+	if (pdef.pattern)
+	    return pdef.pattern;
+
+	if (pdef.type === 'boolean')
+	    return `<true|false>`;
+
+	if (type_fallback && pdef.type)
+	    return `<${pdef.type}>`;
+
+	return;
+    };
+
+    let render_format = function(value, metaData, record) {
+	let pdef = record.data;
+
+	metaData.style = 'white-space:normal;'
+
+	if (pdef.type === 'array' && pdef.items) {
+	    let format = render_simple_format(pdef.items, true);
+	    return `[${Ext.htmlEncode(format)}, ...]`;
+	}
+
+	return Ext.htmlEncode(render_simple_format(pdef) || '');
+    };
+
+    var real_path = function(path) {
+	return path.replace(/^.*\/_upgrade_(\/)?/, "/");
+    };
+
+    var permission_text = function(permission) {
+	let permhtml = "";
+
+	if (permission.user) {
+	    if (!permission.description) {
+		if (permission.user === 'world') {
+		    permhtml += "Accessible without any authentication.";
+		} else if (permission.user === 'all') {
+		    permhtml += "Accessible by all authenticated users.";
+		} else {
+		    permhtml += 'Onyl accessible by user "' +
+			permission.user + '"';
+		}
+	    }
+	} else if (permission.check) {
+	    permhtml += "<pre>Check: " +
+		Ext.htmlEncode(Ext.JSON.encode(permission.check))  + "</pre>";
+	} else if (permission.userParam) {
+	    permhtml += `<div>Check if user matches parameter '${permission.userParam}'`;
+	} else if (permission.or) {
+	    permhtml += "<div>Or<div style='padding-left: 10px;'>";
+	    Ext.Array.each(permission.or, function(sub_permission) {
+		permhtml += permission_text(sub_permission);
+	    })
+	    permhtml += "</div></div>";
+	} else if (permission.and) {
+	    permhtml += "<div>And<div style='padding-left: 10px;'>";
+	    Ext.Array.each(permission.and, function(sub_permission) {
+		permhtml += permission_text(sub_permission);
+	    })
+	    permhtml += "</div></div>";
+	} else {
+	    //console.log(permission);
+	    permhtml += "Unknown syntax!";
+	}
+
+	return permhtml;
+    };
+
+    var render_docu = function(data) {
+	var md = data.info;
+
+	// console.dir(data);
+
+	var items = [];
+
+	var clicmdhash = {
+	    GET: 'get',
+	    POST: 'create',
+	    PUT: 'set',
+	    DELETE: 'delete'
+	};
+
+	Ext.Array.each(['GET', 'POST', 'PUT', 'DELETE'], function(method) {
+	    var info = md[method];
+	    if (info) {
+
+		var usage = "";
+
+		usage += "<table><tr><td>HTTP:&nbsp;&nbsp;&nbsp;</td><td>"
+		    + method + " " + real_path("/api2/json" + data.path) + "</td></tr>";
+
+		var sections = [
+		    {
+			title: 'Description',
+			html: Ext.htmlEncode(info.description),
+			bodyPadding: 10
+		    },
+		    {
+			title: 'Usage',
+			html: usage,
+			bodyPadding: 10
+		    }
+		];
+
+		if (info.parameters && info.parameters.properties) {
+
+		    var pstore = Ext.create('Ext.data.Store', {
+			model: 'pve-param-schema',
+			proxy: {
+			    type: 'memory'
+			},
+			groupField: 'optional',
+			sorters: [
+			    {
+				property: 'name',
+				direction: 'ASC'
+			    }
+			]
+		    });
+
+		    Ext.Object.each(info.parameters.properties, function(name, pdef) {
+			pdef.name = name;
+			pstore.add(pdef);
+		    });
+
+		    pstore.sort();
+
+		    var groupingFeature = Ext.create('Ext.grid.feature.Grouping',{
+			enableGroupingMenu: false,
+			groupHeaderTpl: '<tpl if="groupValue">Optional</tpl><tpl if="!groupValue">Required</tpl>'
+		    });
+
+		    sections.push({
+			xtype: 'gridpanel',
+			title: 'Parameters',
+			features: [groupingFeature],
+			store: pstore,
+			viewConfig: {
+			    trackOver: false,
+			    stripeRows: true
+			},
+			columns: [
+			    {
+				header: 'Name',
+				dataIndex: 'name',
+				flex: 1
+			    },
+			    {
+				header: 'Type',
+				dataIndex: 'type',
+				renderer: render_type,
+				flex: 1
+			    },
+			    {
+				header: 'Default',
+				dataIndex: 'default',
+				flex: 1
+			    },
+			    {
+				header: 'Format',
+				dataIndex: 'type',
+				renderer: render_format,
+				flex: 2
+			    },
+			    {
+				header: 'Description',
+				dataIndex: 'description',
+				renderer: render_description,
+				flex: 6
+			    }
+			]
+		    });
+
+		}
+
+		if (info.returns) {
+
+		    var retinf = info.returns;
+		    var rtype = retinf.type;
+		    if (!rtype && retinf.items)
+			rtype = 'array';
+		    if (!rtype)
+			rtype = 'object';
+
+		    var rpstore = Ext.create('Ext.data.Store', {
+			model: 'pve-param-schema',
+			proxy: {
+			    type: 'memory'
+			},
+			groupField: 'optional',
+			sorters: [
+			    {
+				property: 'name',
+				direction: 'ASC'
+			   }
+			]
+		    });
+
+		    var properties;
+		    if (rtype === 'array' && retinf.items.properties) {
+			properties = retinf.items.properties;
+		    }
+
+		    if (rtype === 'object' && retinf.properties) {
+			properties = retinf.properties;
+		    }
+
+		    Ext.Object.each(properties, function(name, pdef) {
+			pdef.name = name;
+			rpstore.add(pdef);
+		    });
+
+		    rpstore.sort();
+
+		    var groupingFeature = Ext.create('Ext.grid.feature.Grouping',{
+			enableGroupingMenu: false,
+			groupHeaderTpl: '<tpl if="groupValue">Optional</tpl><tpl if="!groupValue">Obligatory</tpl>'
+		    });
+		    var returnhtml;
+		    if (retinf.items) {
+			returnhtml = '<pre>items: ' + Ext.htmlEncode(JSON.stringify(retinf.items, null, 4)) + '</pre>';
+		    }
+
+		    if (retinf.properties) {
+			returnhtml = returnhtml || '';
+			returnhtml += '<pre>properties:' + Ext.htmlEncode(JSON.stringify(retinf.properties, null, 4)) + '</pre>';
+		    }
+
+		    var rawSection = Ext.create('Ext.panel.Panel', {
+			bodyPadding: '0px 10px 10px 10px',
+			html: returnhtml,
+			hidden: true
+		    });
+
+		    sections.push({
+			xtype: 'gridpanel',
+			title: 'Returns: ' + rtype,
+			features: [groupingFeature],
+			store: rpstore,
+			viewConfig: {
+			    trackOver: false,
+			    stripeRows: true
+			},
+		    columns: [
+			{
+			    header: 'Name',
+			    dataIndex: 'name',
+			    flex: 1
+			},
+			{
+			    header: 'Type',
+			    dataIndex: 'type',
+			    renderer: render_type,
+			    flex: 1
+			},
+			{
+			    header: 'Default',
+			    dataIndex: 'default',
+			    flex: 1
+			},
+			{
+			    header: 'Format',
+			    dataIndex: 'type',
+			    renderer: render_format,
+			    flex: 2
+			},
+			{
+			    header: 'Description',
+			    dataIndex: 'description',
+			    renderer: render_description,
+			    flex: 6
+			}
+		    ],
+		    bbar: [
+			{
+			    xtype: 'button',
+			    text: 'Show RAW',
+			    handler: function(btn) {
+				rawSection.setVisible(!rawSection.isVisible());
+				btn.setText(rawSection.isVisible() ? 'Hide RAW' : 'Show RAW');
+			    }}
+		    ]
+		});
+
+		sections.push(rawSection);
+
+
+		}
+
+		if (!data.path.match(/\/_upgrade_/)) {
+		    var permhtml = '';
+
+		    if (!info.permissions) {
+			permhtml = "Root only.";
+		    } else {
+			if (info.permissions.description) {
+			    permhtml += "<div style='white-space:pre-wrap;padding-bottom:10px;'>" +
+				Ext.htmlEncode(info.permissions.description) + "</div>";
+			}
+			permhtml += permission_text(info.permissions);
+		    }
+
+		    // we do not have this information for PBS api
+		    //if (!info.allowtoken) {
+		    //    permhtml += "<br />This API endpoint is not available for API tokens."
+		    //}
+
+		    sections.push({
+			title: 'Required permissions',
+			bodyPadding: 10,
+			html: permhtml
+		    });
+		}
+
+		items.push({
+		    title: method,
+		    autoScroll: true,
+		    defaults: {
+			border: false
+		    },
+		    items: sections
+		});
+	    }
+	});
+
+	var ct = Ext.getCmp('docview');
+	ct.setTitle("Path: " +  real_path(data.path));
+	ct.removeAll(true);
+	ct.add(items);
+	ct.setActiveTab(0);
+    };
+
+    Ext.define('Ext.form.SearchField', {
+	extend: 'Ext.form.field.Text',
+	alias: 'widget.searchfield',
+
+	emptyText: 'Search...',
+
+	flex: 1,
+
+	inputType: 'search',
+	listeners: {
+	    'change': function(){
+
+		var value = this.getValue();
+		if (!Ext.isEmpty(value)) {
+		    store.filter({
+			property: 'path',
+			value: value,
+			anyMatch: true
+		    });
+		} else {
+		    store.clearFilter();
+		}
+	    }
+	}
+    });
+
+    var tree = Ext.create('Ext.tree.Panel', {
+	title: 'Resource Tree',
+	tbar: [
+	    {
+		xtype: 'searchfield',
+	    }
+	],
+	tools: [
+	    {
+		type: 'expand',
+		tooltip: 'Expand all',
+		tooltipType: 'title',
+		callback: (tree) => tree.expandAll(),
+	    },
+	    {
+		type: 'collapse',
+		tooltip: 'Collapse all',
+		tooltipType: 'title',
+		callback: (tree) => tree.collapseAll(),
+	    },
+	],
+        store: store,
+	width: 200,
+        region: 'west',
+        split: true,
+        margins: '5 0 5 5',
+        rootVisible: false,
+	listeners: {
+	    selectionchange: function(v, selections) {
+		if (!selections[0])
+		    return;
+		var rec = selections[0];
+		render_docu(rec.data);
+		location.hash = '#' + rec.data.path;
+	    }
+	}
+    });
+
+    Ext.create('Ext.container.Viewport', {
+	layout: 'border',
+	renderTo: Ext.getBody(),
+	items: [
+	    tree,
+	    {
+		xtype: 'tabpanel',
+		title: 'Documentation',
+		id: 'docview',
+		region: 'center',
+		margins: '5 5 5 0',
+		layout: 'fit',
+		items: []
+	    }
+	]
+    });
+
+    var deepLink = function() {
+	var path = window.location.hash.substring(1).replace(/\/\s*$/, '')
+	var endpoint = store.findNode('path', path);
+
+	if (endpoint) {
+	    tree.getSelectionModel().select(endpoint);
+	    tree.expandPath(endpoint.getPath());
+	    render_docu(endpoint.data);
+	}
+    }
+    window.onhashchange = deepLink;
+
+    deepLink();
+
+});

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

@@ -1,387 +1,79 @@
-Administration Guide
+Backup Client Usage
-====================
+===================
-
-The administration guide.
-
-.. todo:: either add a bit more explanation or remove the previous sentence
-
-Terminology
------------
-
-Backup Content
-~~~~~~~~~~~~~~
-
-When doing deduplication, there are different strategies to get
-optimal results in terms of performance and/or deduplication rates.
-Depending on the type of data, one can split data into *fixed* or *variable*
-sized chunks.
-
-Fixed sized chunking needs almost no CPU performance, and is used to
-backup virtual machine images.
-
-Variable sized chunking needs more CPU power, but is essential to get
-good deduplication rates for file archives.
-
-The backup server supports both strategies.
-
-
-File Archives: ``<name>.pxar``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. see https://moinakg.wordpress.com/2013/06/22/high-performance-content-defined-chunking/
-
-A file archive stores a full directory tree. Content is stored using
-the :ref:`pxar-format`, split into variable sized chunks. The format
-is optimized to achieve good deduplication rates.
-
-
-Image Archives: ``<name>.img``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is used for virtual machine images and other large binary
-data. Content is split into fixed sized chunks.
-
-
-Binary Data (BLOBs)
-^^^^^^^^^^^^^^^^^^^
-
-This type is used to store smaller (< 16MB) binary data such as
-configuration files. Larger files should be stored as image archive.
-
-.. caution:: Please do not store all files as BLOBs. Instead, use the
-   file archive to store whole directory trees.
-
-
-Catalog File: ``catalog.pcat1``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The catalog file is an index for file archives. It contains
-the list of files and is used to speed-up search operations.
-
-
-The Manifest: ``index.json``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The manifest contains the list of all backup files, their
-sizes and checksums. It is used to verify the consistency of a
-backup.
-
-
-Backup Type
-~~~~~~~~~~~
-
-The backup server groups backups by *type*, where *type* is one of:
-
-``vm``
-    This type is used for :term:`virtual machine`\ s. Typically
-    contains the virtual machine's configuration and an image archive
-    for each disk.
-
-``ct``
-    This type is used for :term:`container`\ s. Contains the container's
-    configuration and a single file archive for the container content.
-
-``host``
-    This type is used for backups created from within the backed up machine.
-    Typically this would be a physical host but could also be a virtual machine
-    or container. Such backups may contain file and image archives, there are no restrictions in this regard.
-
-
-Backup ID
-~~~~~~~~~
-
-An unique ID. Usually the virtual machine or container ID. ``host``
-type backups normally use the hostname.
-
-
-Backup Time
-~~~~~~~~~~~
-
-The time when the backup was made.
-
-
-Backup Group
-~~~~~~~~~~~~
-
-The tuple ``<type>/<ID>`` is called a backup group. Such a group
-may contain one or more backup snapshots.
-
-
-Backup Snapshot
-~~~~~~~~~~~~~~~
-
-The triplet ``<type>/<ID>/<time>`` is called a backup snapshot. It
-uniquely identifies a specific backup within a datastore.
-
-.. code-block:: console
-   :caption: Backup Snapshot Examples
-
-    vm/104/2019-10-09T08:01:06Z
-    host/elsa/2019-11-08T09:48:14Z
-
-As you can see, the time format is RFC3399_ with Coordinated
-Universal Time (UTC_, identified by the trailing *Z*).
-
-
-:term:`DataStore`
-~~~~~~~~~~~~~~~~~
-
-A datastore is a place where backups are stored. The current implementation
-uses a directory inside a standard unix file system (``ext4``, ``xfs``
-or ``zfs``) to store the backup data.
-
-Datastores are identified by a simple *ID*. You can configure it
-when setting up the backup server.
-
-
-Backup Server Management
-------------------------
-
-The command line tool to configure and manage the backup server is called
-:command:`proxmox-backup-manager`.
-
-
-Datastore Configuration
-~~~~~~~~~~~~~~~~~~~~~~~
-
-A :term:`datastore` is a place to store backups. You can configure
-multiple datastores. At least one datastore needs to be
-configured. The datastore is identified by a simple `name` and points
-to a directory.
-
-The following command creates a new datastore called ``store1`` on :file:`/backup/disk1/store1`
-
-.. code-block:: console
-
-  # proxmox-backup-manager datastore create store1 /backup/disk1/store1
-
-To list existing datastores run:
-
-.. code-block:: console
-
-  # proxmox-backup-manager datastore list
-  ┌────────┬──────────────────────┬─────────────────────────────┐
-  │ name   │ path                 │ comment                     │
-  ╞════════╪══════════════════════╪═════════════════════════════╡
-  │ store1 │ /backup/disk1/store1 │ This is my default storage. │
-  └────────┴──────────────────────┴─────────────────────────────┘
-
-Finally, it is possible to remove the datastore configuration:
-
-.. code-block:: console
-
-  # proxmox-backup-manager datastore remove store1
-
-.. note:: The above command removes only the datastore configuration. It does
-   not delete any data from the underlying directory.
-
-
-File Layout
-^^^^^^^^^^^
-
-.. todo:: Add datastore file layout example
-
-
-User Management
-~~~~~~~~~~~~~~~
-
-Proxmox Backup support several authentication realms, and you need to
-choose the realm when you add a new user. Possible realms are:
-
-:pam: Linux PAM standard authentication. Use this if you want to
-      authenticate as Linux system user (Users needs to exist on the
-      system).
-
-:pbs: Proxmox Backup Server realm. This type stores hashed passwords in
-      ``/etc/proxmox-backup/shadow.json``.
-
-After installation, there is a single user ``root@pam``, which
-corresponds to the Unix superuser. You can use the
-``proxmox-backup-manager`` command line tool to list or manipulate
-users:
-
-.. code-block:: console
-
-  # proxmox-backup-manager user list
-  ┌─────────────┬────────┬────────┬───────────┬──────────┬────────────────┬────────────────────┐
-  │ userid      │ enable │ expire │ firstname │ lastname │ email          │ comment            │
-  ╞═════════════╪════════╪════════╪═══════════╪══════════╪════════════════╪════════════════════╡
-  │ root@pam    │      1 │        │           │          │                │ Superuser          │
-  └─────────────┴────────┴────────┴───────────┴──────────┴────────────────┴────────────────────┘
-
-The superuser has full administration rights on everything, so you
-normally want to add other users with less privileges:
-
-.. code-block:: console
-
-  # proxmox-backup-manager user create john@pbs --email john@example.com
-
-The create command lets you specify many option like ``--email`` or
-``--password``, but you can update or change any of them using the
-update command later:
-
-.. code-block:: console
-
-  # proxmox-backup-manager user update john@pbs --firstname John --lastname Smith
-  # proxmox-backup-manager user update john@pbs --comment "An example user."
-
-
-.. todo:: Mention how to set password without passing plaintext password as cli argument.
-
-
-The resulting use list looks like this:
-
-.. code-block:: console
-
-  # proxmox-backup-manager user list
-  ┌──────────┬────────┬────────┬───────────┬──────────┬──────────────────┬──────────────────┐
-  │ userid   │ enable │ expire │ firstname │ lastname │ email            │ comment          │
-  ╞══════════╪════════╪════════╪═══════════╪══════════╪══════════════════╪══════════════════╡
-  │ john@pbs │      1 │        │ John      │ Smith    │ john@example.com │ An example user. │
-  ├──────────┼────────┼────────┼───────────┼──────────┼──────────────────┼──────────────────┤
-  │ root@pam │      1 │        │           │          │                  │ Superuser        │
-  └──────────┴────────┴────────┴───────────┴──────────┴──────────────────┴──────────────────┘
-
-Newly created users do not have an permissions. Please read the next
-section to learn how to set access permissions.
-
-If you want to disable an user account, you can do that by setting ``--enable`` to ``0``
-
-.. code-block:: console
-
-  # proxmox-backup-manager user update john@pbs --enable 0
-
-Or completely remove the users with:
-
-.. code-block:: console
-
-  # proxmox-backup-manager user remove john@pbs
-
-
-Access Control
-~~~~~~~~~~~~~~
-
-Users do not have any permission by default. Instead you need to
-specify what is allowed and what not. You can do this by assigning
-roles to users on specific objects like datastores or remotes. The
-following roles exist:
-
-**Admin**
-  The Administrator can do anything.
-
-**Audit**
-  An Auditor can view things, but is not allowed to change settings.
-
-**NoAccess**
-  Disable Access - nothing is allowed.
-
-**DatastoreAdmin**
-  Can do anything on datastores.
-
-**DatastoreAudit**
-  Can view datastore settings and list content. But
-  is not allowed to read the actual data.
-
-**DataStoreReader**
-  Can Inspect datastore content and can do restores.
-
-**DataStoreBackup**
-  Can backup and restore owned backups.
-
-**DatastorePowerUser**
-  Can backup, restore, and prune owned backups.
-
-**RemoteAdmin**
-  Can do anything on remotes.
-
-**RemoteAudit**
-  Can view remote settings.
-
-**RemoteSyncOperator**
-  Is allowed to read data from a remote.
-
-
-
-Backup Client usage
--------------------
 
 The command line client is called :command:`proxmox-backup-client`.
 
+.. _client_repository:
 
-Respository Locations
+Backup Repository Locations
-~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 The client uses the following notation to specify a datastore repository
 on the backup server.
 
-  [[username@]server:]datastore
+  [[username@]server[:port]:]datastore
 
-The default value for ``username`` ist ``root``. If no server is specified, the
+The default value for ``username`` is ``root@pam``. If no server is specified,
-default is the local host (``localhost``).
+the default is the local host (``localhost``).
 
-You can pass the repository with the ``--repository`` command
+You can specify a port if your backup server is only reachable on a different
-line option, or by setting the ``PBS_REPOSITORY`` environment
+port (e.g. with NAT and port forwarding).
-variable.
 
+Note that if the server is 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.
+
+Here some examples of valid repositories and the 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 for the password required for the
+  When set, this value is used for the password required for the backup server.
-  backup server.
+  You can also set this to a API token secret.
 
 ``PBS_ENCRYPTION_PASSWORD``
   When set, this value is used to access the secret encryption key (if
   protected by password).
 
 ``PBS_FINGERPRINT`` When set, this value is used to verify the server
-  certificate (only used if the system CA certificates cannot
+  certificate (only used if the system CA certificates cannot validate the
-  validate the certificate).
+  certificate).
 
 
 Output Format
-~~~~~~~~~~~~~
+-------------
 
-Most commands support the ``--output-format`` parameter. It accepts
+.. include:: output-format.rst
-the following values:
-
-:``text``: Text format (default). Structured data is rendered as a table.
-
-:``json``: JSON (single line).
-
-:``json-pretty``: JSON (multiple lines, nicely formatted).
 
 
-Please use the following environment variables to modify output behavior:
+.. _client_creating_backups:
-
-``PROXMOX_OUTPUT_FORMAT``
-  Defines the default output format.
-
-``PROXMOX_OUTPUT_NO_BORDER``
-  If set (to any value), do not render table borders.
-
-``PROXMOX_OUTPUT_NO_HEADER``
-  If set (to any value), do not render table headers.
-
-.. note:: The ``text`` format is designed to be human readable, and
-   not meant to be parsed by automation tools. Please use the ``json``
-   format if you need to process the output.
-
-
-.. _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 Proxmov VE, see :ref:`pve-integration`.
+.. 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, working
 credentials and need to know the repository name.
@@ -412,17 +104,19 @@ This will prompt you for a password and then uploads a file archive named
 
 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``.
+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_REPOSTORY=backup-server:store1
+  # export PBS_REPOSITORY=backup-server:store1
 
 After this you can execute all commands without specifying the ``--repository``
 option.
 
 One single backup is allowed to contain more than one archive. For example, if
-you want to backup two disks mounted at ``/mmt/disk1`` and ``/mnt/disk2``:
+you want to backup two disks mounted at ``/mnt/disk1`` and ``/mnt/disk2``:
 
 .. code-block:: console
 
@@ -443,11 +137,12 @@ device images. To create a backup of a block device run the following command:
 
   # proxmox-backup-client backup mydata.img:/dev/mylvm/mydata
 
+
 Excluding files/folders from a backup
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sometimes it is desired to exclude certain files or folders from a backup archive.
-To tell the Proxmox backup client when and how to ignore files and directories,
+To tell the Proxmox Backup client when and how to ignore files and directories,
 place a text file called ``.pxarexclude`` in the filesystem hierarchy.
 Whenever the backup client encounters such a file in a directory, it interprets
 each line as glob match patterns for files and directories that are to be excluded
@@ -469,17 +164,17 @@ the given patterns. It is only possible to match files in this directory and its
 all files ending in ``.tmp`` within the directory or subdirectories with the
 following pattern ``**/*.tmp``.
 ``[...]`` matches a single character from any of the provided characters within
-the brackets. ``[!...]`` does the complementary and matches any singe character
+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 one single digit.
 
-The order of the glob match patterns defines if a file is included or
+The order of the glob match patterns defines whether a file is included or
-excluded, later entries win over previous ones.
+excluded, that is to say later entries override previous ones.
 This is also true for match patterns encountered deeper down the directory tree,
 which can override a previous exclusion.
 Be aware that excluded directories will **not** be read by the backup client.
-A ``.pxarexclude`` file in a subdirectory will have no effect.
+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.
 
@@ -528,11 +223,14 @@ Restoring this backup will result in:
     restored/subfolder1:
     .  ..  file2
 
-Encryption
-^^^^^^^^^^
 
-Proxmox backup supports client side encryption with AES-256 in GCM_
+.. _client_encryption:
-mode. First you need to create an encryption key:
+
+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
 
@@ -546,6 +244,8 @@ extra protection, you can also create it without a password:
 
   # 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
 
@@ -554,27 +254,129 @@ extra protection, you can also create it without a 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``.
 
-.. todo:: Explain master-key
+
+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 to avoid data
+The regular creation of backups is a necessary step to avoiding data
-loss. More important, however, is the restoration. It is good practice to perform
+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 problems.
 
 First, you need to find the snapshot which you want to restore. The snapshot
-command gives a list of all snapshots on the server:
+list command provides a list of all the snapshots on the server:
 
 .. code-block:: console
 
-  # proxmox-backup-client snapshots
+  # proxmox-backup-client snapshot list
   ┌────────────────────────────────┬─────────────┬────────────────────────────────────┐
   │ snapshot                       │        size │ files                              │
   ╞════════════════════════════════╪═════════════╪════════════════════════════════════╡
@@ -602,8 +404,8 @@ backup.
 
   # 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 ``ìndex.json`` file in the
+To get the contents of any archive, you can restore the ``index.json`` file in the
-repository and restore it to '-'. This will dump the content to the standard output.
+repository to the target path '-'. This will dump the contents to the standard output.
 
 .. code-block:: console
 
@@ -611,7 +413,7 @@ repository and restore it to '-'. This will dump the content to the standard out
 
 
 Interactive Restores
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 If you only want to restore a few individual files, it is often easier
 to use the interactive recovery shell.
@@ -624,7 +426,7 @@ to use the interactive recovery shell.
   bin        boot       dev        etc        home       lib        lib32
   ...
 
-The interactive recovery shell is a minimalistic command line interface that
+The interactive recovery shell is a minimal command line interface that
 utilizes the metadata stored in the catalog to quickly list, navigate and
 search files in a file archive.
 To restore files, you can select them individually or match them with a glob
@@ -640,7 +442,7 @@ 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.
 
-Being able to quickly search the contents of the archive is a often needed feature.
+Being able to quickly search the contents of the archive is a commonly needed feature.
 That's where the catalog is most valuable.
 For example:
 
@@ -659,40 +461,39 @@ subdirectory and add the corresponding pattern to the list for subsequent restor
 all files in the archive matching the patterns to ``/target/path`` on the local
 host. This will scan the whole archive.
 
-With ``restore /target/path`` you can restore the sub-archive given by the current
+The ``restore`` command can be used to restore all the files contained within
-working directory to the local target path ``/target/path`` on your host.
+the backup archive. This is most helpful when paired with the ``--pattern
-By additionally passing a glob pattern with ``--pattern <glob>``, the restore is
+<glob>`` option, as it allows you to restore all files matching a specific
-further limited to files matching the pattern.
+pattern. For example, if you wanted to restore configuration files
-For example:
+located in ``/etc``, you could do the following:
 
 .. code-block:: console
 
-  pxar:/ > cd /etc/
+  pxar:/ > restore target/ --pattern etc/**/*.conf
-  pxar:/etc/ > restore /target/ --pattern **/*.conf
   ...
 
-The above will scan trough all the directories below ``/etc`` and restore all
+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 mountpoint on your host.
 
 .. code-block:: console
 
-  # proxmox-backup-client mount host/backup-client/2020-01-29T11:29:22Z root.pxar /mnt
+  # proxmox-backup-client mount host/backup-client/2020-01-29T11:29:22Z root.pxar /mnt/mountpoint
-  # ls /mnt
+  # 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 content of the archive in a seamless manner.
+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 servers datastore, this can cause some additional network and CPU
+    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.
 
@@ -700,10 +501,10 @@ To unmount the filesystem use the ``umount`` command on the mountpoint:
 
 .. code-block:: console
 
-  # umount /mnt
+  # umount /mnt/mountpoint
 
 Login and Logout
-~~~~~~~~~~~~~~~~
+----------------
 
 The client tool prompts you to enter the logon password as soon as you
 want to access the backup server. The server checks your credentials
@@ -726,23 +527,48 @@ To remove the ticket, issue a logout:
   # 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 forget <snapshot>
+  # proxmox-backup-client snapshot forget <snapshot>
 
 
 .. caution:: This command removes all archives in this backup
    snapshot. They will be inaccessible and unrecoverable.
 
 
-The manual removal is sometimes required, but normally the prune
+Although manual removal is sometimes required, the ``prune``
-command is used to systematically delete older backups. Prune lets
+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:
 
@@ -787,7 +613,7 @@ backup is retained.
 
 
 You can use the ``--dry-run`` option to test your settings. This only
-shows the list of existing snapshots and which action prune would take.
+shows the list of existing snapshots and what actions prune would take.
 
 .. code-block:: console
 
@@ -808,13 +634,13 @@ shows the list of existing snapshots and which action prune would take.
 
 .. 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:`garbage-collection`.
+   space you need to perform :ref:`client_garbage-collection`.
 
 
-.. _garbage-collection:
+.. _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
@@ -829,6 +655,17 @@ unused data blocks are removed.
   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
 
@@ -849,54 +686,52 @@ unused data blocks are removed.
   TASK OK
 
 
-.. todo:: howto run garbage-collection at regular intervalls (cron)
+.. todo:: howto run garbage-collection at regular intervals (cron)
 
+Benchmarking
+------------
 
-.. _pve-integration:
+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.
 
-`Proxmox VE`_ integration
+You can run a benchmark using the ``benchmark`` subcommand of
--------------------------
+``proxmox-backup-client``:
 
-You need to define a new storage with type 'pbs' on your `Proxmox VE`_
+.. note:: The TLS speed test is only included if a :ref:`backup server
-node. The following example uses ``store2`` as storage name, and
+  repository is specified <client_repository>`.
-assumes the server address is ``localhost``, and you want to connect
-as ``user1@pbs``.
 
 .. code-block:: console
 
-  # pvesm add pbs store2 --server localhost --datastore store2
+  # proxmox-backup-client benchmark
-  # pvesm set store2 --username user1@pbs --password <secret>
+  Uploaded 1517 chunks in 5 seconds.
-
+  Time per request: 3309 microseconds.
-If your backup server uses a self signed certificate, you need to add
+  TLS speed: 1267.41 MB/s
-the certificate fingerprint to the configuration. You can get the
+  SHA256 speed: 2066.73 MB/s
-fingerprint by running the following command on the backup server:
+  Compression speed: 775.11 MB/s
-
+  Decompress speed: 1233.35 MB/s
-.. code-block:: console
+  AES256/GCM speed: 3688.27 MB/s
-
+  Verify speed: 783.43 MB/s
-  # proxmox-backup-manager cert  info |grep Fingerprint
+  ┌───────────────────────────────────┬─────────────────────┐
-  Fingerprint (sha256): 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
+  │ Name                              │ Value               │
-
+  ╞═══════════════════════════════════╪═════════════════════╡
-Please add that fingerprint to your configuration to establish a trust
+  │ TLS (maximal backup upload speed) │ 1267.41 MB/s (103%) │
-relationship:
+  ├───────────────────────────────────┼─────────────────────┤
-
+  │ SHA256 checksum computation speed │ 2066.73 MB/s (102%) │
-.. code-block:: console
+  ├───────────────────────────────────┼─────────────────────┤
-
+  │ ZStd level 1 compression speed    │ 775.11 MB/s (103%)  │
-  # pvesm set store2 --fingerprint  64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
+  ├───────────────────────────────────┼─────────────────────┤
-
+  │ ZStd level 1 decompression speed  │ 1233.35 MB/s (103%) │
-After that you should be able to see storage status with:
+  ├───────────────────────────────────┼─────────────────────┤
-
+  │ Chunk verification speed          │ 783.43 MB/s (103%)  │
-.. code-block:: console
+  ├───────────────────────────────────┼─────────────────────┤
-
+  │ AES256 GCM encryption speed       │ 3688.27 MB/s (101%) │
-  # pvesm status --storage store2
+  └───────────────────────────────────┴─────────────────────┘
-  Name             Type     Status           Total            Used       Available        %
-  store2            pbs     active      3905109820      1336687816      2568422004   34.23%
 
 
+.. note:: The percentages given in the output table correspond to a
+  comparison against a Ryzen 7 2700X.
 
-.. include:: command-line-tools.rst
+You can also pass the ``--output-format`` parameter to output stats in ``json``,
-
+rather than the default table format.
-.. include:: services.rst
-
-.. include host system admin at the end
-
-.. include:: sysadmin.rst

docs/backup-protocol.rst

@@ -1,19 +1,140 @@
 Backup Protocol
 ===============
 
-.. todo:: add introduction to HTTP2 based backup protocols
+Proxmox Backup Server uses a REST based API. While the management
+interface use normal HTTP, the actual backup and restore interface use
+HTTP/2 for improved performance. Both HTTP and HTTP/2 are well known
+standards, so the following section assumes that you are familiar on
+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 protocol name::
 
-.. include:: backup-protocol-api.rst
+  GET /api2/json/backup HTTP/1.1
+  UPGRADE: proxmox-backup-protocol-v1
+
+The server replies with HTTP 101 Switching Protocol status code,
+and you can then issue REST commands on that 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 chunk with variable size)
+
+The following section gives a short introduction how to upload such
+files. Please use the `API Viewer <api-viewer/index.html>`_ for
+details about available REST commands.
 
 
-Reader Protocol API
+Upload Blobs
--------------------
+~~~~~~~~~~~~
 
-.. todo:: describe backup reader protocol
+Uploading blobs is done 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 needs to end with ``.blob``, and is automatically added
+to the backup manifest.
+
+
+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 use 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 to 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.
+
+
+Upload Dynamic Indexes
+~~~~~~~~~~~~~~~~~~~~~~
+
+Dynamic indexes are use 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 to chunk digests
+and offsets.
+
+You create a dynamic 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 file name needs to end with ``.didx``, and is automatically added
+to the backup manifest.
+
+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 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 kind of files:
+
+- Chunks and blobs (binary data)
+
+- Fixed Indexes (List of chunks with fixed size)
+
+- Dynamic Indexes (List of chunk with variable size)
+
+The following section gives a short introduction how to download such
+files. Please use the `API Viewer <api-viewer/index.html>`_ for details about
+available REST commands.
+
+
+Download Blobs
+~~~~~~~~~~~~~~
+
+Downloading blobs is done using ``GET /download``. The HTTP body contains the
+data encoded as :ref:`Data Blob <data-blob-format>`.
+
+
+Download Chunks
+~~~~~~~~~~~~~~~
+
+Downloading chunks is done using ``GET /chunk``. The HTTP body contains the
+data encoded as :ref:`Data Blob <data-blob-format>`).
+
+
+Download Index Files
+~~~~~~~~~~~~~~~~~~~~
+
+Downloading index files is done 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 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 set timezone on 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
+if they are due every minute. This means that even if
+`calendar events` can contain seconds, it will only be checked
+once a minute.
+
+Also, all schedules will be checked against the timezone set
+in the `Proxmox Backup`_ server.

docs/command-line-tools.rst

@@ -6,13 +6,18 @@ Command Line Tools
 
 .. include:: proxmox-backup-client/description.rst
 
+``proxmox-file-restore``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: proxmox-file-restore/description.rst
+
 ``proxmox-backup-manager``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. include:: proxmox-backup-manager/description.rst
 
 ``pxar``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~
 
 .. include:: pxar/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:
+Those command are available when you start an interactive restore shell:
 
 .. code-block:: console
 
@@ -26,6 +26,27 @@ 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``
 --------
 

docs/conf.py

@@ -17,10 +17,13 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
+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
@@ -45,7 +48,10 @@ PygmentsBridge.latex_formatter = CustomLatexFormatter
 # Add any Sphinx extension module names here, as strings. They can be
 # 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
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -68,7 +74,7 @@ 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
@@ -76,9 +82,11 @@ author = 'Proxmox Support Team'
 # built documents.
 #
 # The short X.Y version.
-version = '0.2'
+vstr = lambda s: '<devbuild>' if s is None else str(s)
+
+version = vstr(os.getenv('DEB_VERSION_UPSTREAM'))
 # The full version, including alpha/beta/rc tags.
-release = '0.2-1'
+release = vstr(os.getenv('DEB_VERSION'))
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -89,25 +97,21 @@ 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',
+    'config/*/man5.rst',
-    'proxmox-backup-proxy/man1.rst',
-    'pxar/man1.rst',
     'epilog.rst',
     'pbs-copyright.rst',
-    'sysadmin.rst',
+    'local-zfs.rst'
     'package-repositories.rst',
 ]
 
@@ -140,7 +144,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 ----------------------------------------------
@@ -148,13 +152,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 = []
@@ -171,7 +216,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
@@ -184,6 +229,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.
@@ -196,14 +245,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.
@@ -224,7 +267,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.
 #
@@ -264,6 +307,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 collon.
+
+:propagate: Propagate permissions down the hierachrchy
+
+:path: The object path
+
+:User/Token: List of users and token
+
+: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 @@
+The file contains a list of datastore configuration sections. Each
+section starts with a 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 a 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 a 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 a 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 a 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 a header ``lto: <name>``,
+followed by the drive configuration options.
+
+Tape changer configurations starts with  ``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 onyl 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 a header ``user: <name>``,
+followed by the user configuration options.
+
+API token configuration starts with a 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 a 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 resides inside 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
@@ -11,8 +11,11 @@
 .. _Container: https://en.wikipedia.org/wiki/Container_(virtualization)
 .. _Zstandard: https://en.wikipedia.org/wiki/Zstandard
 .. _Proxmox: https://www.proxmox.com
+.. _Proxmox Community Forum: https://forum.proxmox.com
 .. _Proxmox Virtual Environment: https://www.proxmox.com/proxmox-ve
-.. _Proxmox Backup: https://www.proxmox.com/proxmox-backup
+.. 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/
 .. _SHA-256: https://en.wikipedia.org/wiki/SHA-2
@@ -35,3 +38,6 @@
 .. _RFC3399: 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,72 @@
+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 1.x     | Debian 10 (Buster) | 2020-11       | tba        | tba                |
++-----------------------+--------------------+---------------+------------+--------------------+
+
+
+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 incremental and data is
+deduplicated on the server.
+This minimizes both the storage consumed and the network impact.

docs/file-formats.rst

@@ -6,7 +6,113 @@ 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
+
+Compression algorithm is ``zstd``. 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 contains a 16 byte IV, followed by a 16
+byte Authenticated Encyryption (AE) tag, followed by the encrypted
+data:
+
+.. list-table::
+
+   * - ``MAGIC: [u8; 8]``
+   * - ``CRC32: [u8; 4]``
+   * - ``ÌV: [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]``,
+     - Sha256 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]``
+     - next chunk
+   * - ...
+     - next chunk ...
+
+
+.. _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]``,
+     - Sha256 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

@@ -16,7 +16,7 @@ Glossary
    Datastore
 
       A place to store backups. A directory which contains the backup data.
-      The current implemenation is file-system based.
+      The current implementation is file-system based.
 
    `Rust`_
 
@@ -46,3 +46,8 @@ Glossary
       kernel driver handles filesystem requests and sends them to a
       userspace application.
 
+   Remote
+
+      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.

docs/gui.rst

@@ -0,0 +1,148 @@
+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 the one specified during the installation
+process.
+
+
+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 and logout.
+* **Sidebar**: On the left. This contains the configuration options for
+  the server.
+* **Configuration Panel**: In the center. This contains the control interface for the
+  configuration 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 configuration options, such as
+time and network 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`)
+* **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
+* **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, managing tape media sets,
+inventories, drives, changers and the tape backup jobs itself.
+
+It 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 contains a button to create 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