bump version to 0.9.1-1

This allows TLSv1.3, and let the client select ciphers. After this
change AES is prefered over chacha20, so TLS speed is now much faster.

.gitignore

@@ -3,3 +3,4 @@ local.mak
 **/*.rs.bk
 /etc/proxmox-backup.service
 /etc/proxmox-backup-proxy.service
+build/

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "proxmox-backup"
-version = "0.1.3"
+version = "0.9.1"
 authors = ["Dietmar Maurer <dietmar@proxmox.com>"]
 edition = "2018"
 license = "AGPL-3"
@@ -14,44 +14,54 @@ name = "proxmox_backup"
 path = "src/lib.rs"
 
 [dependencies]
-base64 = "0.10"
+apt-pkg-native = "0.3.1" # custom patched version
+base64 = "0.12"
+bitflags = "1.2.1"
 bytes = "0.5"
-chrono = "0.4" # Date and time library for Rust
 crc32fast = "1"
 endian_trait = { version = "0.6", features = ["arrays"] }
-failure = "0.1"
+anyhow = "1.0"
 futures = "0.3"
 h2 = { version = "0.2", features = ["stream"] }
+handlebars = "3.0"
 http = "0.2"
-hyper = "0.13"
+hyper = "0.13.6"
 lazy_static = "1.4"
 libc = "0.2"
 log = "0.4"
-native-tls = "0.2"
 nix = "0.16"
+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-alpha"
+pin-utils = "0.1.0"
-proxmox = { version = "0.1.18", features = [ "sortable-macro", "api-macro" ] }
+pathpatterns = "0.1.2"
-#proxmox = { git = "ssh://gitolite3@proxdev.maurer-it.com/rust/proxmox", version = "0.1.2", features = [ "sortable-macro", "api-macro" ] }
+proxmox = { version = "0.4.3", features = [ "sortable-macro", "api-macro", "websocket" ] }
-#proxmox = { path = "../proxmox/proxmox", features = [ "sortable-macro", "api-macro" ] }
+#proxmox = { git = "git://git.proxmox.com/git/proxmox", version = "0.1.2", features = [ "sortable-macro", "api-macro" ] }
+#proxmox = { path = "../proxmox/proxmox", features = [ "sortable-macro", "api-macro", "websocket" ] }
+proxmox-fuse = "0.1.0"
+pxar = { version = "0.6.1", features = [ "tokio-io", "futures-io" ] }
+#pxar = { path = "../pxar", features = [ "tokio-io", "futures-io" ] }
 regex = "1.2"
-rustyline = "5.0.5"
+rustyline = "6"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 siphasher = "0.3"
 syslog = "4.0"
-tokio = { version = "0.2.9", features = [ "blocking", "fs", "io-util", "macros", "rt-threaded", "signal", "stream", "tcp", "time", "uds" ] }
+tokio = { version = "0.2.9", features = [ "blocking", "fs", "dns", "io-util", "macros", "process", "rt-threaded", "signal", "stream", "tcp", "time", "uds" ] }
 tokio-openssl = "0.4.0"
-tokio-util = { version = "0.2.0", features = [ "codec" ] }
+tokio-util = { version = "0.3", features = [ "codec" ] }
 tower-service = "0.3.0"
+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"
 xdg = "2.2"
 zstd = { version = "0.4", features = [ "bindgen" ] }
+nom = "5.1"
+crossbeam-channel = "0.4"
 
 [features]
 default = []

Makefile

@@ -37,10 +37,16 @@ CARGO ?= cargo
 COMPILED_BINS := \
 	$(addprefix $(COMPILEDIR)/,$(USR_BIN) $(USR_SBIN) $(SERVICE_BIN))
 
-DEBS= ${PACKAGE}-server_${DEB_VERSION}_${ARCH}.deb ${PACKAGE}-client_${DEB_VERSION}_${ARCH}.deb
+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
 DOC_DEB=${PACKAGE}-docs_${DEB_VERSION}_all.deb
 
+DEBS=${SERVER_DEB} ${SERVER_DBG_DEB} ${CLIENT_DEB} ${CLIENT_DBG_DEB}
+
 DSC = rust-${PACKAGE}_${DEB_VERSION}.dsc
 
 DESTDIR=
@@ -63,10 +69,12 @@ doc:
 .PHONY: build
 build:
 	rm -rf build
+	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), \
@@ -74,18 +82,21 @@ 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: $(DOC_DEB) $(DEBS)
+
 .PHONY: dsc
 dsc: $(DSC)
 $(DSC): build
@@ -135,7 +146,8 @@ install: $(COMPILED_BINS)
 	$(MAKE) -C docs install
 
 .PHONY: upload
-upload: ${DEBS}
+upload: ${SERVER_DEB} ${CLIENT_DEB} ${DOC_DEB}
 	# check if working directory is clean
 	git diff --exit-code --stat && git diff --exit-code --stat --staged
-	tar cf - ${DEBS} | ssh -X repoman@repo.proxmox.com upload --product pbs --dist buster
+	tar cf - ${SERVER_DEB} ${SERVER_DBG_DEB} ${DOC_DEB} | 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 "pbs,pve,pmg" --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,20 @@ 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.

TODO.rst

@@ -1,22 +1,37 @@
 TODO list for Proxmox Backup
 ============================
 
-* user management api
 
 * disk management api
 
-* start writing server GUI
-
 * improve catalog shell commands
 
 * improve user documentation
 
 
+GUI
+===
+
+* fix network/dns GUI (network/dns api changed)
+
+* user/acl/permission management GUI
+
+* implement GUI to configure remotes
+
+* implement fancy DatastoreStatus.js dashboard
+
+* implement PVE GUI to add PBS storage (with convenient copy/paste
+  functionality, like we have for cluster join)
+
+
+
 Chores:
 =======
 
 * move tools/xattr.rs and tools/acl.rs to proxmox/sys/linux/
 
+* remove pbs-* systemd timers and services on package purge
+
 
 Suggestions
 ===========

debian/changelog

@@ -1,3 +1,602 @@
+rust-proxmox-backup (0.9.1-1) unstable; urgency=medium
+
+  * TLS speedups (use SslAcceptor::mozilla_intermediate_v5)
+
+  * introduction.rst: add History
+
+  * fix #2847: proxmox-backup-client: add change-owner cmd
+
+  * proxmox-backup-client key: rename 'paper-key' command to 'paperkey'
+
+  * don't require WorkerTask in backup/ (introduce TaskState trait)
+
+  * fix #3070: replace internal with public URLs
+
+  * backup: index readers: drop useless shared lock
+
+  * add "Build" section to README.rst
+
+  * reader: actually allow users to downlod their own backups
+
+  * reader: track index chunks and limit access
+
+  * Userid: fix borrow/deref recursion
+
+  * depend on proxmox 0.4.3
+
+  * api: datastore: require allocate privilege for deletion
+
+  * fuse_loop: handle unmap on crashed instance
+
+  * fuse_loop: wait for instance to close after killing
+
+  * fuse_loop: add automatic cleanup of run files and dangling instances
+
+  * mount/map: use names for map/unmap for easier use
+
+  * ui: network: remove create VLAN option
+
+  * ui: Dashboard/TaskSummary: add Verifies to the Summary
+
+  * ui: implment task history limit and make it configurable
+
+  * docs: installation: add system requirements section
+
+  * client: implement map/unmap commands for .img backups
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 14 Oct 2020 13:42:12 +0200
+
+rust-proxmox-backup (0.9.0-2) unstable; urgency=medium
+
+  * ui: RemoteEdit: only send delete on update
+
+ -- Proxmox Support Team <support@proxmox.com>  Fri, 02 Oct 2020 15:37:45 +0200
+
+rust-proxmox-backup (0.9.0-1) unstable; urgency=medium
+
+  * use ParallelHandler to verify chunks
+
+  * client: add new paper-key command to CLI tool
+
+  * server: split task list in active and archived
+
+  * tools: add logrotate module and use it for archived tasks, allowing to save
+    more than 100 thousands of tasks efficiently in the archive
+
+  * require square [brackets] for ipv6 addresses and fix ipv6 handling for
+    remotes/sync jobs
+
+  * ui: RemoteEdit: make comment and fingerprint deletable
+
+  * api/disks: create zfs: enable import systemd service unit for newly created
+    ZFS pools
+
+  * client and remotes: add support to specify a custom port number. The server
+    is still always listening on 8007, but you can now use things like reverse
+    proxies or port mapping.
+
+  * ui: RemoteEdit: allow to specify a port in the host field
+
+  * client pull: log progress
+
+  * various fixes and improvements
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 01 Oct 2020 16:19:40 +0200
+
+rust-proxmox-backup (0.8.21-1) unstable; urgency=medium
+
+  * depend on crossbeam-channel
+
+  * speedup sync jobs (allow up to 4 worker threads)
+
+  * improve docs
+
+  * use jobstate mechanism for verify/garbage_collection schedules
+
+  * proxy: fix error handling in prune scheduling
+
+ -- Proxmox Support Team <support@proxmox.com>  Fri, 25 Sep 2020 13:20:19 +0200
+
+rust-proxmox-backup (0.8.20-1) unstable; urgency=medium
+
+  * improve sync speed
+
+  * benchmark: use compressable data to get more realistic result
+
+  * docs: add onlineHelp to some panels
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 24 Sep 2020 13:15:45 +0200
+
+rust-proxmox-backup (0.8.19-1) unstable; urgency=medium
+
+  * src/api2/reader.rs: use std::fs::read instead of tokio::fs::read
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 22 Sep 2020 13:30:27 +0200
+
+rust-proxmox-backup (0.8.18-1) unstable; urgency=medium
+
+  * src/client/pull.rs: allow up to 20 concurrent download streams
+
+  * docs: add version and date to HTML index
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 22 Sep 2020 12:39:26 +0200
+
+rust-proxmox-backup (0.8.17-1) unstable; urgency=medium
+
+  * src/client/pull.rs: open temporary manifest with truncate(true)
+
+  * depend on proxmox 0.4.1
+
+  * fix #3017: check array boundaries before using
+
+  * datastore/prune schedules: use JobState for tracking of schedules
+
+  * improve docs
+
+  * fix #3015: allow user self-service
+
+  * add verification scheduling to proxmox-backup-proxy
+
+  * fix #3014: allow DataStoreAdmins to list DS config
+
+  * depend on pxar 0.6.1
+
+  * fix #2942: implement lacp bond mode and bond_xmit_hash_policy
+
+  * api2/pull: make pull worker abortable
+
+  * fix #2870: renew tickets in HttpClient
+
+  * always allow retrieving (censored) subscription info
+
+  * fix #2957: allow Sys.Audit access to node RRD
+
+  * backup: check all referenced chunks actually exist
+
+  * backup: check verify state of previous backup before allowing reuse
+
+  * avoid chrono dependency
+
+ -- Proxmox Support Team <support@proxmox.com>  Mon, 21 Sep 2020 14:08:32 +0200
+
+rust-proxmox-backup (0.8.16-1) unstable; urgency=medium
+
+  * BackupDir: make constructor fallible
+
+  * handle invalid mtime when formating entries
+
+  * ui/docs: add onlineHelp button for syncjobs
+
+  * docs: add section for calendar events
+
+  * tools/systemd/parse_time: enable */x syntax for calendar events
+
+  * docs: set html img width limitation through css
+
+  * docs: use alabaster theme
+
+  * server: set http2 max frame size
+
+  * doc: Add section "FAQ"
+
+ -- Proxmox Support Team <support@proxmox.com>  Fri, 11 Sep 2020 15:54:57 +0200
+
+rust-proxmox-backup (0.8.15-1) unstable; urgency=medium
+
+  *  verify: skip benchmark directory
+
+  * add benchmark flag to backup creation for proper cleanup when running
+    a benchmark
+
+  * mount: fix mount subcommand
+
+  * ui: only mark backup encrypted if there are any files
+
+  * fix #2983: improve tcp performance
+
+  * improve ui and docs
+
+  * verify: rename corrupted chunks with .bad extension
+
+  * gc: remove .bad files on garbage collect
+
+  * ui: add translation support
+
+  * server/worker_task: fix upid_read_status
+
+  * tools/systemd/time: enable dates for calendarevents
+
+  * server/worker_task: fix 'unknown' status for some big task logs
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 10 Sep 2020 09:25:59 +0200
+
+rust-proxmox-backup (0.8.14-1) unstable; urgency=medium
+
+  * verify speed up: use separate IO thread, use datastore-wide cache (instead
+    of per group)
+
+  * ui: datastore content: improve encrypted column
+
+  * ui: datastore content: show more granular verify state, especially for
+    backup group rows
+
+  * verify: log progress in percent
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 02 Sep 2020 09:36:47 +0200
+
+rust-proxmox-backup (0.8.13-1) unstable; urgency=medium
+
+  * improve and add to documentation
+
+  * save last verify result in snapshot manifest and show it in the GUI
+
+  * gc: use human readable units for summary in task log
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 27 Aug 2020 16:12:07 +0200
+
+rust-proxmox-backup (0.8.12-1) unstable; urgency=medium
+
+  * verify: speedup - only verify chunks once
+
+  * verify: sort backup groups
+
+  * bump pxar dep to 0.4.0
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 25 Aug 2020 08:55:52 +0200
+
+rust-proxmox-backup (0.8.11-1) unstable; urgency=medium
+
+  * improve sync jobs, allow to stop them and better logging
+
+  * fix #2926: make network interfaces parser more flexible
+
+  * fix #2904: zpool status: parse also those vdevs without READ/ẀRITE/...
+    statistics
+
+  * api2/node/services: turn service api calls into workers
+
+  * docs: add sections describing ACL related commands and describing
+    benchmarking
+
+  * docs: general grammar, wording and typo improvements
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 19 Aug 2020 19:20:03 +0200
+
+rust-proxmox-backup (0.8.10-1) unstable; urgency=medium
+
+  * ui: acl: add improved permission selector
+
+  * services: make reload safer and default to it in gui
+
+  * ui: rework DataStore content Panel
+
+  * ui: add search box to DataStore content
+
+  * ui: DataStoreContent: keep selection and expansion on reload
+
+  * upload_chunk: allow upload of empty blobs
+
+  * fix #2856: also check whole device for device mapper
+
+  * ui: fix error when reloading DataStoreContent
+
+  * ui: fix in-progress snapshots always showing as "Encrypted"
+
+  * update to pxar 0.3 to support negative timestamps
+
+  * fix #2873: if --pattern is used, default to not extracting
+
+  * finish_backup: test/verify manifest at server side
+
+  * finish_backup: add chunk_upload_stats to manifest
+
+  * src/api2/admin/datastore.rs: add API to get/set Notes for backus
+
+  * list_snapshots: Returns new "comment" property (first line from notes)
+
+  * pxar: create: attempt to use O_NOATIME
+
+  * systemd/time: fix weekday wrapping on month
+
+  * pxar: better error handling on extract
+
+  * pxar/extract: fixup path stack for errors
+
+  * datastore: allow browsing signed pxar files
+
+  * GC: use time pre phase1 to calculate min_atime in phase2
+
+  * gui: user: fix #2898 add dialog to set password
+
+  * fix #2909: handle missing chunks gracefully in garbage collection
+
+  * finish_backup: mark backup as finished only after checks have passed
+
+  * fix: master-key: upload RSA encoded key with backup
+
+  * admin-guide: add section explaining master keys
+
+  * backup: only allow finished backups as base snapshot
+
+  * datastore api: only decode unencrypted indices
+
+  * datastore api: verify blob/index csum from manifest
+
+  * sync, blobs and chunk readers: add more checks and verification
+
+  * verify: add more checks, don't fail on first error
+
+  * mark signed manifests as such
+
+  * backup/prune/forget: improve locking
+
+  * backup: ensure base snapshots are still available after backup
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 11 Aug 2020 15:37:29 +0200
+
+rust-proxmox-backup (0.8.9-1) unstable; urgency=medium
+
+  * improve termprocy (console) behavior on updating proxmox-backup-server and
+    other daemon restarts
+
+  * client: improve upload log output and speed calculation
+
+  * fix #2885: client upload: bail on duplicate backup targets
+
+ -- Proxmox Support Team <support@proxmox.com>  Fri, 24 Jul 2020 11:24:07 +0200
+
+rust-proxmox-backup (0.8.8-1) unstable; urgency=medium
+
+  * pxar: .pxarexclude: match behavior from absolute paths to the one described
+    in the documentation and use byte based paths
+
+  * catalog shell: add exit command
+
+  * manifest: revert signature canonicalization to old behaviour. Fallout from
+    encrypted older backups is expected and was ignored due to the beta status
+    of Proxmox Backup.
+
+  * documentation: various improvements and additions
+
+  * cached user info: print privilege path in error message
+
+  * docs: fix #2851 Add note about GC grace period
+
+  * api2/status: fix datastore full estimation bug if there where (almost) no
+    change for several days
+
+  * schedules, calendar event: support the 'weekly' special expression
+
+  * ui: sync job: group remote fields and use "Source" in labels
+
+  * ui: add calendar event selector
+
+  * ui: sync job: change default to false for "remove-vanished" for new jobs
+
+  * fix #2860: skip in-progress snapshots when syncing
+
+  * fix #2865: detect and skip vanished snapshots
+
+  * fix #2871: close FDs when scanning backup group, avoid leaking
+
+  * backup: list images: handle walkdir error, catch "lost+found" special
+    directory
+
+  * implement AsyncSeek for AsyncIndexReader
+
+  * client: rework logging upload info like size or bandwidth
+
+  * client writer: do not output chunklist for now on verbose=true
+
+  * add initial API for listing available updates and updating the APT
+    database
+
+  * ui: add xterm.js console implementation
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 23 Jul 2020 12:16:05 +0200
+
+rust-proxmox-backup (0.8.7-2) unstable; urgency=medium
+
+  * support restoring file attributes from pxar archives
+
+  * docs: additions and fixes
+
+  * ui: running tasks: update limit to 100
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 14 Jul 2020 12:05:25 +0200
+
+rust-proxmox-backup (0.8.6-1) unstable; urgency=medium
+
+  * ui: add button for easily showing the server fingerprint dashboard
+
+  * proxmox-backup-client benchmark: add --verbose flag and improve output
+    format
+
+  * docs: reference PDF variant in HTML output
+
+  * proxmox-backup-client: add simple version command
+
+  * improve keyfile and signature handling in catalog and manifest
+
+ -- Proxmox Support Team <support@proxmox.com>  Fri, 10 Jul 2020 11:34:14 +0200
+
+rust-proxmox-backup (0.8.5-1) unstable; urgency=medium
+
+  * fix cross process task listing
+
+  * docs: expand datastore documentation
+
+  * docs: add remotes and sync-jobs and schedules
+
+  * bump pathpatterns to 0.1.2
+
+  * ui: align version and user-menu spacing with pve/pmg
+
+  * ui: make username a menu-button
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 09 Jul 2020 15:32:39 +0200
+
+rust-proxmox-backup (0.8.4-1) unstable; urgency=medium
+
+  * add TaskButton in header
+
+  * simpler lost+found pattern
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 09 Jul 2020 14:28:24 +0200
+
+rust-proxmox-backup (0.8.3-1) unstable; urgency=medium
+
+  * get_disks: don't fail on zfs_devices
+
+  * allow some more characters for zpool list
+
+  * ui: adapt for new sign-only crypt mode
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 09 Jul 2020 13:55:06 +0200
+
+rust-proxmox-backup (0.8.2-1) unstable; urgency=medium
+
+  * buildsys: also upload debug packages
+
+  * src/backup/manifest.rs: rename into_string -> to_string
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 09 Jul 2020 11:58:51 +0200
+
+rust-proxmox-backup (0.8.1-1) unstable; urgency=medium
+
+  * remove authhenticated data blobs (not needed)
+
+  * add signature to manifest
+
+  * improve docs
+
+  * client: introduce --keyfd parameter
+
+  * ui improvements
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 09 Jul 2020 10:01:25 +0200
+
+rust-proxmox-backup (0.8.0-1) unstable; urgency=medium
+
+  * implement  get_runtime_with_builder
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 07 Jul 2020 10:15:26 +0200
+
+rust-proxmox-backup (0.7.0-1) unstable; urgency=medium
+
+  *  implement clone for RemoteChunkReader
+
+  * improve docs
+
+  * client: add --encryption boolen parameter
+
+  * client: use default encryption key if it is available
+
+  * d/rules: do not compress .pdf files
+
+  * ui: various fixes
+
+  * add beta text with link to bugtracker
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 07 Jul 2020 07:40:05 +0200
+
+rust-proxmox-backup (0.6.0-1) unstable; urgency=medium
+
+  * make ReadChunk not require mutable self.
+
+  * ui: increase timeout for snapshot listing
+
+  * ui: consistently spell Datastore without space between words
+
+  * ui: disk create: sync and improve 'add-datastore' checkbox label
+
+  * proxmox-backup-client: add benchmark command
+
+  * pxar: fixup 'vanished-file' logic a bit
+
+  * ui: add verify button
+
+ -- Proxmox Support Team <support@proxmox.com>  Fri, 03 Jul 2020 09:45:52 +0200
+
+rust-proxmox-backup (0.5.0-1) unstable; urgency=medium
+
+  * partially revert commit 1f82f9b7b5d231da22a541432d5617cb303c0000
+
+  * ui: allow to Forget (delete) backup snapshots
+
+  * pxar: deal with files changing size during archiving
+
+ -- Proxmox Support Team <support@proxmox.com>  Mon, 29 Jun 2020 13:00:54 +0200
+
+rust-proxmox-backup (0.4.0-1) unstable; urgency=medium
+
+  * change api for incremental backups mode
+
+  * zfs disk management gui
+
+ -- Proxmox Support Team <support@proxmox.com>  Fri, 26 Jun 2020 10:43:27 +0200
+
+rust-proxmox-backup (0.3.0-1) unstable; urgency=medium
+
+  * support incremental backups mode
+
+  * new disk management
+
+  * single file restore for container backups
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 24 Jun 2020 10:12:57 +0200
+
+rust-proxmox-backup (0.2.3-1) unstable; urgency=medium
+
+  * tools/systemd/time: fix compute_next_event for weekdays
+
+  * improve display of 'next run' for sync jobs
+
+  * fix csum calculation for images which do not have a 'chunk_size' aligned
+    size
+
+  * add parser for zpool list output
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 04 Jun 2020 10:39:06 +0200
+
+rust-proxmox-backup (0.2.2-1) unstable; urgency=medium
+
+  * proxmox-backup-client.rs: implement quiet flag
+
+  * client restore: don't add server file ending if already specified
+
+  * src/client/pull.rs: also download client.log.blob
+
+  * src/client/pull.rs: more verbose logging
+
+  * gui improvements
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 03 Jun 2020 10:37:12 +0200
+
+rust-proxmox-backup (0.2.1-1) unstable; urgency=medium
+
+  * ui: move server RRD statistics to 'Server Status' panel
+
+  * ui/api: add more server statistics
+
+  * ui/api: add per-datastore usage and performance statistics over time
+
+  * ui: add initial remote config management panel
+
+  * remotes: save passwords as base64
+
+  * gather zpool io stats
+
+  * various fixes/improvements
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 28 May 2020 17:39:33 +0200
+
+rust-proxmox-backup (0.2.0-1) unstable; urgency=medium
+
+  * see git changelog (too many changes)
+
+ -- Proxmox Support Team <support@proxmox.com>  Mon, 25 May 2020 19:17:03 +0200
+
 rust-proxmox-backup (0.1.3-1) unstable; urgency=medium
 
   * use SectionConfig from proxmox 0.1.18-1
@@ -56,4 +655,3 @@ proxmox-backup (0.1-1) unstable; urgency=medium
   * first try
 
  -- Proxmox Support Team <support@proxmox.com>  Fri, 30 Nov 2018 13:03:28 +0100
-

debian/control

@@ -0,0 +1,136 @@
+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.1-~~),
+ librust-base64-0.12+default-dev,
+ librust-bitflags-1+default-dev (>= 1.2.1-~~),
+ librust-bytes-0.5+default-dev,
+ librust-crc32fast-1+default-dev,
+ librust-crossbeam-channel-0.4+default-dev,
+ librust-endian-trait-0.6+arrays-dev,
+ librust-endian-trait-0.6+default-dev,
+ librust-futures-0.3+default-dev,
+ librust-h2-0.2+default-dev,
+ librust-h2-0.2+stream-dev,
+ librust-handlebars-3+default-dev,
+ librust-http-0.2+default-dev,
+ librust-hyper-0.13+default-dev (>= 0.13.6-~~),
+ librust-lazy-static-1+default-dev (>= 1.4-~~),
+ librust-libc-0.2+default-dev,
+ librust-log-0.4+default-dev,
+ librust-nix-0.16+default-dev,
+ librust-nom-5+default-dev (>= 5.1-~~),
+ librust-num-traits-0.2+default-dev,
+ librust-once-cell-1+default-dev (>= 1.3.1-~~),
+ librust-openssl-0.10+default-dev,
+ librust-pam-0.7+default-dev,
+ librust-pam-sys-0.5+default-dev,
+ librust-pathpatterns-0.1+default-dev (>= 0.1.2-~~),
+ librust-percent-encoding-2+default-dev (>= 2.1-~~),
+ librust-pin-utils-0.1+default-dev,
+ librust-proxmox-0.4+api-macro-dev (>= 0.4.3-~~),
+ librust-proxmox-0.4+default-dev (>= 0.4.3-~~),
+ librust-proxmox-0.4+sortable-macro-dev (>= 0.4.3-~~),
+ librust-proxmox-0.4+websocket-dev (>= 0.4.3-~~),
+ librust-proxmox-fuse-0.1+default-dev,
+ librust-pxar-0.6+default-dev (>= 0.6.1-~~),
+ librust-pxar-0.6+futures-io-dev (>= 0.6.1-~~),
+ librust-pxar-0.6+tokio-io-dev (>= 0.6.1-~~),
+ librust-regex-1+default-dev (>= 1.2-~~),
+ librust-rustyline-6+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-tokio-0.2+blocking-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+default-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+dns-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+fs-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+io-util-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+macros-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+process-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+rt-threaded-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+signal-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+stream-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+tcp-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+time-dev (>= 0.2.9-~~),
+ librust-tokio-0.2+uds-dev (>= 0.2.9-~~),
+ librust-tokio-openssl-0.4+default-dev,
+ librust-tokio-util-0.3+codec-dev,
+ librust-tokio-util-0.3+default-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-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,
+ debhelper (>= 12~),
+ bash-completion,
+ pve-eslint,
+ python3-docutils,
+ python3-pygments,
+ rsync,
+ fonts-dejavu-core <!nodoc>,
+ fonts-lato <!nodoc>,
+ fonts-open-sans <!nodoc>,
+ graphviz <!nodoc>,
+ latexmk <!nodoc>,
+ python3-sphinx <!nodoc>,
+ texlive-fonts-extra <!nodoc>,
+ texlive-fonts-recommended <!nodoc>,
+ texlive-xetex <!nodoc>,
+ xindy <!nodoc>
+Maintainer: Proxmox Support Team <support@proxmox.com>
+Standards-Version: 4.4.1
+Vcs-Git: 
+Vcs-Browser: 
+Homepage: https://www.proxmox.com
+
+Package: proxmox-backup-server
+Architecture: any
+Depends: fonts-font-awesome,
+         libjs-extjs (>= 6.0.1),
+         libzstd1 (>= 1.3.8),
+         lvm2,
+         pbs-i18n,
+         proxmox-backup-docs,
+         proxmox-mini-journalreader,
+         proxmox-widget-toolkit (>= 2.3-1),
+         pve-xtermjs (>= 4.7.0-1),
+         smartmontools,
+         ${misc:Depends},
+         ${shlibs:Depends},
+Recommends: zfsutils-linux,
+Description: Proxmox Backup Server daemon with tools and GUI
+ This package contains the Proxmox Backup Server daemons and related
+ tools. This includes a web-based graphical user interface.
+
+Package: proxmox-backup-client
+Architecture: any
+Depends: 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,
+         ${misc:Depends},
+Architecture: all
+Description: Proxmox Backup Documentation
+ This package contains the Proxmox Backup Documentation files.

debian/control.in

@@ -3,17 +3,25 @@ Architecture: any
 Depends: fonts-font-awesome,
          libjs-extjs (>= 6.0.1),
          libzstd1 (>= 1.3.8),
+         lvm2,
+         pbs-i18n,
+         proxmox-backup-docs,
          proxmox-mini-journalreader,
-         proxmox-widget-toolkit,
+         proxmox-widget-toolkit (>= 2.3-1),
+         pve-xtermjs (>= 4.7.0-1),
+         smartmontools,
          ${misc:Depends},
          ${shlibs:Depends},
+Recommends: zfsutils-linux,
 Description: Proxmox Backup Server daemon with tools and GUI
  This package contains the Proxmox Backup Server daemons and related
  tools. This includes a web-based graphical user interface.
 
 Package: proxmox-backup-client
 Architecture: any
-Depends: ${misc:Depends}, ${shlibs:Depends}
+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.

debian/debcargo.toml

@@ -11,8 +11,32 @@ vcs_git = ""
 vcs_browser = ""
 maintainer = "Proxmox Support Team <support@proxmox.com>"
 section = "admin"
-build_depends = [ "debhelper (>= 12~)", "bash-completion" ]
+build_depends = [
-build_depends_excludes = [ "debhelper (>=11)" ]
+  "debhelper (>= 12~)",
+  "bash-completion",
+  "pve-eslint",
+  "python3-docutils",
+  "python3-pygments",
+  "rsync",
+  "fonts-dejavu-core <!nodoc>",
+  "fonts-lato <!nodoc>",
+  "fonts-open-sans <!nodoc>",
+  "graphviz <!nodoc>",
+  "latexmk <!nodoc>",
+  "python3-sphinx <!nodoc>",
+  "texlive-fonts-extra <!nodoc>",
+  "texlive-fonts-recommended <!nodoc>",
+  "texlive-xetex <!nodoc>",
+  "xindy <!nodoc>",
+]
+build_depends_excludes = [
+  "debhelper (>=11)",
+]
 
 [packages.lib]
-depends = [ "libacl1-dev", "libsystemd-dev", "libfuse3-dev", "uuid-dev" ]
+depends = [
+  "libacl1-dev",
+  "libfuse3-dev",
+  "libsystemd-dev",
+  "uuid-dev",
+]

debian/lintian-overrides

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

debian/postinst

@@ -0,0 +1,34 @@
+#!/bin/sh
+
+set -e
+
+#DEBHELPER#
+
+case "$1" in
+    configure)
+	# modeled after dh_systemd_start output
+	systemctl --system daemon-reload >/dev/null || true
+	if [ -n "$2" ]; then
+		_dh_action=try-reload-or-restart
+	else
+		_dh_action=start
+	fi
+	deb-systemd-invoke $_dh_action proxmox-backup.service proxmox-backup-proxy.service >/dev/null || true
+
+	# 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
+	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,10 @@
+#!/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' >/dev/null || true
+fi

debian/proxmox-backup-docs.links

@@ -0,0 +1 @@
+/usr/share/doc/proxmox-backup/proxmox-backup.pdf /usr/share/doc/proxmox-backup/html/proxmox-backup.pdf

debian/proxmox-backup-server.install

@@ -1,10 +1,12 @@
 etc/proxmox-backup-proxy.service /lib/systemd/system/
 etc/proxmox-backup.service /lib/systemd/system/
 etc/proxmox-backup-banner.service /lib/systemd/system/
+etc/pbstest-beta.list /etc/apt/sources.list.d/
 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/sbin/proxmox-backup-manager
+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/proxmox_logo.png

debian/rules

@@ -37,11 +37,14 @@ override_dh_auto_install:
 	    PROXY_USER=backup \
 	    LIBDIR=/usr/lib/$(DEB_HOST_MULTIARCH)
 
-override_dh_installinit:
+override_dh_installsystemd:
-	dh_installinit
+	# note: we start/try-reload-restart services manually in postinst
-	dh_installinit --name proxmox-backup-proxy
+	dh_installsystemd --no-start --no-restart-after-upgrade
 
 # 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_compress:
+	dh_compress -X.pdf

docs/Makefile

@@ -1,11 +1,5 @@
 include ../defines.mk
 
-ifeq ($(BUILD_MODE), release)
-COMPILEDIR := ../target/release
-else
-COMPILEDIR := ../target/debug
-endif
-
 GENERATED_SYNOPSIS := 						\
 	proxmox-backup-client/synopsis.rst			\
 	proxmox-backup-client/catalog-shell-synopsis.rst 	\
@@ -26,6 +20,14 @@ 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) .
 
@@ -65,18 +67,27 @@ 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 $< >$@
 
+.PHONY: onlinehelpinfo
+onlinehelpinfo:
+	@echo "Generating OnlineHelpInfo.js..."
+	$(SPHINXBUILD) -b proxmox-scanrefs $(ALLSPHINXOPTS) $(BUILDDIR)/scanrefs
+	@echo "Build finished. OnlineHelpInfo.js is in $(BUILDDIR)/scanrefs."
+
 .PHONY: html
-html: ${GENERATED_SYNOPSIS}
+html: ${GENERATED_SYNOPSIS} images/proxmox-logo.svg custom.css conf.py
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	cp images/proxmox-logo.svg $(BUILDDIR)/html/_static/
+	cp custom.css $(BUILDDIR)/html/_static/
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: latexpdf
 latexpdf: ${GENERATED_SYNOPSIS}
+	@echo "Requires python3-sphinx, texlive-xetex, xindy and texlive-fonts-extra"
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
+	@echo "Running LaTeX files through xelatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+	@echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 .PHONY: epub3
 epub3: ${GENERATED_SYNOPSIS}

docs/_ext/proxmox-scanrefs.py

@@ -0,0 +1,134 @@
+#!/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:\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',
+        }
+        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)
+                    labelid = node['ids'][1] # [0] is predefined by sphinx, we need [1] for explicit ones
+                    title = cast(nodes.title, node[0])
+                    logger.info('traversing section {}'.format(title.astext()))
+                    ref_name = getattr(title, 'rawsource', title.astext())
+
+                    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 = []
+        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/administration-guide.rst

@@ -1,737 +0,0 @@
-Administration Guide
-====================
-
-The administration guide.
-
-
-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.
-
-Therefore, 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 whole directory tree. Content is stored using
-the :ref:`pxar-format`, split into variable sized chunks. The format
-is specially 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) binaries like
-configuration data. 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 basically an index for file archive. It contains
-the list of files, and is used to speedup search operations.
-
-
-The Manifest: ``index.json``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The manifest contains the list of all backup files, including
-file 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 configuration and an image archive
-    for each disk.
-
-``ct``
-    This type is used for :term:`container`\ s. Contains the container
-    configuration and a single file archive for the container content.
-
-``host``
-    This type is used for physical host, or if you want to run backups
-    manually from inside virtual machines or containers. Such backups
-    may contain file and image archives (no restrictions here).
-
-
-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
-~~~~~~~~~~~~
-
-We call the tuple ``<type>/<ID>`` a backup group. Such group
-may contains one or more backup snapshots.
-
-
-Backup Snapshot
-~~~~~~~~~~~~~~~
-
-We call the triplet ``<type>/<ID>/<time>`` 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 is formatted as RFC3399_ using Coordinated
-Universal Time (UTC_, identified by the trailing *Z*).
-
-
-:term:`DataStore`
-~~~~~~~~~~~~~~~~~
-
-A datastore is a place to store backups. The current implementation
-uses a directory inside a standard unix file system (``ext4``, ``xfs``
-or ``zfs``) to store backup data.
-
-Datastores are identified by a simple *ID*. You can configure that
-when setting up the backup server.
-
-
-Backup Server Management
-------------------------
-
-The command line tool to configure and manage the server is called
-:command:`proxmox-backup-manager`.
-
-
-Datastore Configuration
-~~~~~~~~~~~~~~~~~~~~~~~
-
-A :term:`datastore` is a place to store backups. You can configure
-several datastores, but you need at least one of them. The datastore is identified by a simple `name` and point 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 use:
-
-.. code-block:: console
-
-  # proxmox-backup-manager datastore list
-  store1 /backup/disk1/store1
-
-Finally, it is also possible to remove the datastore configuration:
-
-.. code-block:: console
-
-  # proxmox-backup-manager datastore remove store1
-
-.. note:: Above command removes the datastore configuration. It does
-   not delete any data from the underlying directory.
-
-
-File Layout
-^^^^^^^^^^^
-
-.. todo:: Add datastore file layout example
-
-
-Backup Client usage
--------------------
-
-The command line client is called :command:`proxmox-backup-client`.
-
-
-Respository Locations
-~~~~~~~~~~~~~~~~~~~~~
-
-The client uses a special repository notation to specify a datastore
-on the backup server.
-
-  [[username@]server:]datastore
-
-If you do not specify a ``username`` the default is ``root@pam``. The
-default for server is to use the local host (``localhost``).
-
-You can pass the repository by setting the ``--repository`` command
-line options, or by setting the ``PBS_REPOSITORY`` environment
-variable.
-
-
-Environment Variables
-~~~~~~~~~~~~~~~~~~~~~
-
-``PBS_REPOSITORY``
-  The default backup repository.
-
-``PBS_PASSWORD``
-  When set, this value is used for the password required for the
-  backup server.
-
-``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
-  validate the certificate).
-
-
-Output Format
-~~~~~~~~~~~~~
-
-Most commands support the ``--output-format`` parameter, which can be
-set to 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:
-
-``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, but
-   not meant to be parsed by automation tools. Please use the ``json``
-   format for such purpose because it is machine readable.
-
-
-.. _creating-backups:
-
-Creating Backups
-~~~~~~~~~~~~~~~~
-
-This section explains how to create backup on physical host, or from
-inside virtual machines or containers. Such backups may contain file
-and image archives (no restrictions here).
-
-.. note:: If you want to backup virtual machines or containers see :ref:`pve-integration`.
-
-The prerequisite is that you have already set up (or can access) a
-backup server. It is assumed that you know the repository name and
-credentials. In the following examples we simply use ``backup-server:store1``.
-
-.. code-block:: console
-
-  # proxmox-backup-client backup root.pxar:/ --repository backup-server:store1
-  Starting backup: host/elsa/2019-12-03T09:35:01Z
-  Client name: elsa
-  skip mount point: "/boot/efi"
-  skip mount point: "/dev"
-  skip mount point: "/run"
-  skip mount point: "/sys"
-  Uploaded 12129 chunks in 87 seconds (564 MB/s).
-  End Time: 2019-12-03T10:36:29+01:00
-
-This will prompt you for a password and then uploads a file archive named
-``root.pxar`` containing all the files in the ``/`` directory.
-
-.. Caution:: Please note that proxmox-backup-client does not
-   automatically include mount points. Instead, you will see a short
-   ``skip mount point`` notice for each of them. The idea is that you
-   create a separate file archive for each mounted disk. You can also
-   explicitly include them using the ``--include-dev`` option
-   (i.e. ``--include-dev /boot/efi``). You can use this option
-   multiple times, once for each mount point you want to include.
-
-The ``--repository`` option is sometimes quite long and is used by all
-commands. You can avoid having to enter this value by setting the
-environment variable ``PBS_REPOSITORY``.
-
-.. code-block:: console
-
-  # export PBS_REPOSTORY=backup-server:store1
-
-You can then execute all commands without specifying the ``--repository``
-option.
-
-One single backup is allowed to contain more than one archive. For example, assume you want to backup two disks mounted at ``/mmt/disk1`` and ``/mnt/disk2``:
-
-.. code-block:: console
-
-  # proxmox-backup-client backup disk1.pxar:/mnt/disk1 disk2.pxar:/mnt/disk2
-
-This create a backup of both disks.
-
-The backup command takes a list of backup specifications, which
-include archive name on the server, the type of the archive, and the
-archive source at the client. The format is quite simple to understand:
-
-    <archive-name>.<type>:<source-path>
-
-Common types are ``.pxar`` for file archives, and ``.img`` for block
-device images. Thus it is quite easy to create a backup for a block
-device:
-
-.. code-block:: console
-
-  # 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.
-Using the proxmox backup client this is possible via simple text based
-``.pxarexclude`` files placed in the filesystem hierarchy.
-
-Whenever such a file is encountered in a directory, the backup client reads its
-content and lines are interpreted as glob match patterns for files/directories
-to exclude from the archive.
-The file must contain a single glob pattern on each line. Empty lines are ignored.
-The same is true for lines starting with ``#``, indicating a line containing comments.
-Lines starting with ``!`` correspond to glob match patterns for explicit inclusion
-of files previously excluded by a match. This allows for example to exclude
-all entries in a directory except for a few single files.
-Lines ending in ``/`` match directory entries only.
-The folder containing the ``.pxarexclude`` file is considered to be the root of
-the given patterns. It is only possible to match files in this or below this folder.
-
-``\`` is used to escape glob characters. ``?`` matches any single character,
-``*`` matches any character including the empty string.
-``**`` is used to match also subdirectories and can be used to exclude for example
-all files ending in ``.tmp`` within the directory or a subdirectory by 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
-not contained within the brackets. It is also possible to specify ranges by two
-characters separated by ``-``. For example ``[a-z]`` matches any lowercase
-alphabetic character, ``[0-9]`` matches any one single digit.
-
-The order of the glob match patterns defines if the file is finally included or
-excluded, later entries win over previous ones.
-This is also true for match patterns encountered deeper down the directory tree,
-which may then override a previous exclusion.
-Note however that folders marked for exclusion are not read by the client,
-so ``.pxarexclude`` files contained within have no effect.
-``.pxarexclude`` files are treated as regular files and are also included in the
-backup archive.
-
-For example, consider the following folder structure:
-
-.. code-block:: console
-
-    # ls -aR folder
-    folder/:
-    .  ..  .pxarexclude  subfolder0  subfolder1
-
-    folder/subfolder0:
-    .  ..  file0  file1  file2  file3  .pxarexclude
-
-    folder/subfolder1:
-    .  ..  file0  file1  file2  file3
-
-The ``.pxarexclude`` files containing the following:
-
-.. code-block:: console
-
-    # cat folder/.pxarexclude
-    /subfolder0/file1
-    /subfolder1/*
-    !/subfolder1/file2
-
-.. code-block:: console
-
-    # cat folder/subfolder0/.pxarexclude
-    file3
-
-This would exclude ``file1`` and ``file3`` in ``subfolder0`` and all of
-``subfolder1`` except ``file2``.
-
-Restoring this archive form backup results in:
-
-.. code-block:: console
-
-    ls -aR restored
-    restored/:
-    .  ..  .pxarexclude  subfolder0  subfolder1
-
-    restored/subfolder0:
-    .  ..  file0  file2  .pxarexclude
-
-    restored/subfolder1:
-    .  ..  file2
-
-Encryption
-^^^^^^^^^^
-
-Proxmox backup support client side encryption using AES-256 in GCM_
-mode. You first need to create an encryption key in order to use that:
-
-.. code-block:: console
-
-  # proxmox-backup-client key create my-backup.key
-  Encryption Key Password: **************
-
-The key is password protected by default. If you do not need this
-extra protection, you can also create it without a password:
-
-.. code-block:: console
-
-  # proxmox-backup-client key create /path/to/my-backup.key --kdf  none
-
-
-.. code-block:: console
-
-  # proxmox-backup-client backup etc.pxar:/etc --keyfile /path/to/my-backup.key
-  Password: *********
-  Encryption Key Password: **************
-  ...
-
-
-You can avoid having to enter the passwords by setting the environment
-variables ``PBS_PASSWORD`` and ``PBS_ENCRYPTION_PASSWORD``.
-
-.. todo:: Explain master-key
-
-
-Restoring Data
-~~~~~~~~~~~~~~
-
-The regular creation of backups is a necessary step to avoid data
-loss. More important, however, is the restoration. Be sure to perform
-periodic recovery tests to ensure that you can access your data in
-case of problems.
-
-First, you need to find the snapshot you want to restore. The snapshot
-command gives you a list of all snapshots on the server:
-
-.. code-block:: console
-
-  # proxmox-backup-client snapshots
-  ...
-  host/elsa/2019-12-03T09:30:15Z | 51788646825 | root.pxar catalog.pcat1 index.json
-  host/elsa/2019-12-03T09:35:01Z | 51790622048 | root.pxar catalog.pcat1 index.json
-  ...
-
-You can also inspect the catalog to find specific files.
-
-.. code-block:: console
-
-  # proxmox-backup-client catalog dump host/elsa/2019-12-03T09:35:01Z
-  ...
-  d "./root.pxar.didx/etc/cifs-utils"
-  l "./root.pxar.didx/etc/cifs-utils/idmap-plugin"
-  d "./root.pxar.didx/etc/console-setup"
-  ...
-
-The restore command lets you restore a single archive from the
-backup.
-
-.. code-block:: console
-
-  # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z root.pxar /target/path/
-
-You can instead simply download the contents of any archive using '-'
-instead of ``/target/path``. This dumps the content to standard
-output:
-
-.. code-block:: console
-
-  # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z index.json -
-
-
-Interactive Restores
-^^^^^^^^^^^^^^^^^^^^
-
-If you only want to restore a few individual files, it is often easier
-to use the interactive recovery shell.
-
-.. code-block:: console
-
-  # proxmox-backup-client catalog shell host/elsa/2019-12-03T09:35:01Z root.pxar
-  Starting interactive shell
-  pxar:/ > ls
-  bin        boot       dev        etc        home       lib        lib32
-  ...
-
-The interactive recovery shell is a minimalistic command line interface that
-utilizes the metadata stored in the catalog for you to quickly list, navigate and
-search files contained within a file archive.
-You can select individual files as well as select files matched by a glob pattern
-for restore.
-
-The use of the catalog for navigation reduces the overhead otherwise caused by
-network traffic and decryption, as instead of downloading and decrypting
-individual encrypted chunks from the chunk-store to access the metadata, we only
-need to download and decrypt the catalog.
-The actual chunks are only accessed if the metadata in the catalog is not enough
-or for the actual restore.
-
-Similar to common UNIX shells ``cd`` and ``ls`` are the commands used to change
-working directory and list directory contents of 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.
-That's where the catalog is most valuable.
-For example:
-
-.. code-block:: console
-
-  pxar:/ > find etc/ **/*.txt --select
-  "/etc/X11/rgb.txt"
-  pxar:/ > list-selected
-  etc/**/*.txt
-  pxar:/ > restore-selected /target/path
-  ...
-
-This will find and print all files ending in ``.txt`` located in ``etc/`` or a
-subdirectory and add the corresponding pattern to the list for subsequent restores.
-``list-selected`` shows these patterns and ``restore-selected`` finally restores
-all files in the archive matching the patterns to ``/target/path`` on the local
-host. This will scan the whole archive.
-
-With ``restore /target/path`` you can restore the sub-archive given by the current
-working directory to the local target path ``/target/path`` on your host.
-By additionally passing a glob pattern with ``--pattern <glob>``, the restore is
-further limited to files matching the pattern.
-For example:
-
-.. code-block:: console
-
-  pxar:/ > cd /etc/
-  pxar:/etc/ > restore /target/ --pattern **/*.conf
-  ...
-
-The above will scan trough 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
-  # ls /mnt
-  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.
-
-.. note:: As the FUSE connection needs to fetch and decrypt chunks from the
-    backup servers datastore, this can cause some additional network and CPU
-    load on your host, depending on the operations you perform on the mounted
-    filesystem.
-
-To unmount the filesystem simply use the ``umount`` command on the mountpoint:
-
-.. code-block:: console
-
-  # umount /mnt
-
-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
-and responds with a ticket that is valid for two hours. The client
-tool automatically stores that ticket and use it for further requests
-to this server.
-
-You can also manually trigger this login/logout using the login and
-logout commands:
-
-.. code-block:: console
-
-  # proxmox-backup-client login
-  Password: **********
-
-To remove the ticket, simply issue a logout:
-
-.. code-block:: console
-
-  # proxmox-backup-client logout
-
-
-Pruning and Removing Backups
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can manually delete a backup snapshot using the ``forget``
-command:
-
-.. code-block:: console
-
-  # proxmox-backup-client forget <snapshot>
-
-
-.. caution:: This command removes all the archives in this backup
-   snapshot so that they are inaccessible and unrecoverable.
-
-
-Such manual removal is sometimes required, but normally the prune
-command is used to systematically delete older backups. Prune lets
-you specify which backup snapshots you want to keep. There are the
-following retention options:
-
-``--keep-last <N>``
-  Keep the last ``<N>`` backup snapshots.
-
-``--keep-hourly <N>``
-  Keep backups for the last ``<N>`` different hours. If there is more than one
-  backup for a single hour, only the latest one is kept.
-
-``--keep-daily <N>``
-  Keep backups for the last ``<N>`` different days. If there is more than one
-  backup for a single day, only the latest one is kept.
-
-``--keep-weekly <N>``
-  Keep backups for the last ``<N>`` different weeks. If there is more than one
-  backup for a single week, only the latest one is kept.
-
-  .. note:: The weeks start on Monday and end on Sunday. The software
-     uses the `ISO week date`_ system and correctly handles weeks at
-     the end of the year.
-
-``--keep-monthly <N>``
-  Keep backups for the last ``<N>`` different months. If there is more than one
-  backup for a single month, only the latest one is kept.
-
-``--keep-yearly <N>``
-  Keep backups for the last ``<N>`` different years. If there is more than one
-  backup for a single year, only the latest one is kept.
-
-
-Those retention options are processed in the order given above. Each
-option covers a specific period of time. We say that backups within
-this period are covered by this option. The next option does not take
-care of already covered backups and only considers older backups.
-
-The prune command also looks for unfinished and incomplete backups and
-removes them unless they are newer than the last successful backup. In
-this case, the last failed backup is retained.
-
-.. code-block:: console
-
-  # proxmox-backup-client prune <group> --keep-daily 7 --keep-weekly 4 --keep-monthly 3
-
-
-You can use the ``--dry-run`` option to test your settings. This just
-shows the list of existing snapshots and what action prune would take
-on that.
-
-.. code-block:: console
-
-  # proxmox-backup-client prune host/elsa --dry-run --keep-daily 1 --keep-weekly 3
-  retention options: --keep-daily 1 --keep-weekly 3
-  Testing prune on store "store2" group "host/elsa"
-  host/elsa/2019-12-04T13:20:37Z keep
-  host/elsa/2019-12-03T09:35:01Z remove
-  host/elsa/2019-11-22T11:54:47Z keep
-  host/elsa/2019-11-21T12:36:25Z remove
-  host/elsa/2019-11-10T10:42:20Z keep
-
-
-.. note:: Neither the ``prune`` command nor the ``forget`` command free space
-   in the chunk-store. The chunk-store still contains the data blocks
-   unless you are performing :ref:`garbage-collection`.
-
-
-.. _garbage-collection:
-
-Garbage Collection
-~~~~~~~~~~~~~~~~~~
-
-The ``prune`` command removes only the backup index files, not the data
-from the data store. This task is left to the garbage collection
-command. It is therefore recommended to carry out garbage collection
-regularly.
-
-The garbage collection works in two phases. In the first phase, all
-data blocks that are still in use are marked. In the second phase,
-unused data blocks are removed.
-
-.. note:: This command needs to read all existing backup index files
-  and touches the complete chunk-store. This can take a long time
-  depending on the number of chunks and the speed of the underlying
-  disks.
-
-
-.. code-block:: console
-
-  # proxmox-backup-client garbage-collect
-  starting garbage collection on store store2
-  Start GC phase1 (mark used chunks)
-  Start GC phase2 (sweep unused chunks)
-  percentage done: 1, chunk count: 219
-  percentage done: 2, chunk count: 453
-  ...
-  percentage done: 99, chunk count: 21188
-  Removed bytes: 411368505
-  Removed chunks: 203
-  Original data bytes: 327160886391
-  Disk bytes: 52767414743 (16 %)
-  Disk chunks: 21221
-  Average chunk size: 2486565
-  TASK OK
-
-
-.. todo:: howto run garbage-collection at regular intervalls (cron)
-
-
-.. _pve-integration:
-
-`Proxmox VE`_ integration
--------------------------
-
-
-.. include:: command-line-tools.rst
-
-.. include:: services.rst
-
-.. include host system admin at the end
-
-.. include:: sysadmin.rst

docs/backup-client.rst

@@ -0,0 +1,712 @@
+Backup Client Usage
+===================
+
+The command line client is called :command:`proxmox-backup-client`.
+
+
+Repository Locations
+--------------------
+
+The client uses the following notation to specify a datastore repository
+on the backup server.
+
+  [[username@]server[:port]:]datastore
+
+The default value for ``username`` is ``root@pam``.  If no server is specified,
+the default is the local host (``localhost``).
+
+You can specify a port if your backup server is only reachable on a different
+port (e.g. with NAT and port forwarding).
+
+Note that if the server is an IPv6 address, you have to write it with
+square brackets (e.g. [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
+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
+  backup server.
+
+``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
+  validate the certificate).
+
+
+Output Format
+-------------
+
+Most commands support the ``--output-format`` parameter. It accepts
+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:
+
+``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 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.
+In the following examples we use ``backup-server:store1``.
+
+.. code-block:: console
+
+  # proxmox-backup-client backup root.pxar:/ --repository backup-server:store1
+  Starting backup: host/elsa/2019-12-03T09:35:01Z
+  Client name: elsa
+  skip mount point: "/boot/efi"
+  skip mount point: "/dev"
+  skip mount point: "/run"
+  skip mount point: "/sys"
+  Uploaded 12129 chunks in 87 seconds (564 MB/s).
+  End Time: 2019-12-03T10:36:29+01:00
+
+This will prompt you for a password and then uploads a file archive named
+``root.pxar`` containing all the files in the ``/`` directory.
+
+.. Caution:: Please note that the proxmox-backup-client does not
+   automatically include mount points. Instead, you will see a short
+   ``skip mount point`` notice for each of them. The idea is to
+   create a separate file archive for each mounted disk. You can
+   explicitly include them using the ``--include-dev`` option
+   (i.e. ``--include-dev /boot/efi``). You can use this option
+   multiple times for each mount point that should be included.
+
+The ``--repository`` option can get quite long and is used by all
+commands. You can avoid having to enter this value by setting the
+environment variable ``PBS_REPOSITORY``. Note that if you would like this to remain set
+over multiple sessions, you should instead add the below line to your
+``.bashrc`` file.
+
+.. code-block:: console
+
+  # export PBS_REPOSITORY=backup-server:store1
+
+After this you can execute all commands without 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 ``/mnt/disk1`` and ``/mnt/disk2``:
+
+.. code-block:: console
+
+  # proxmox-backup-client backup disk1.pxar:/mnt/disk1 disk2.pxar:/mnt/disk2
+
+This creates a backup of both disks.
+
+The backup command takes a list of backup specifications, which
+include the archive name on the server, the type of the archive, and the
+archive source at the client. The format is:
+
+    <archive-name>.<type>:<source-path>
+
+Common types are ``.pxar`` for file archives, and ``.img`` for block
+device images. To create a backup of a block device run the following command:
+
+.. code-block:: console
+
+  # proxmox-backup-client backup mydata.img:/dev/mylvm/mydata
+
+
+Excluding files/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,
+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
+from the backup.
+
+The file must contain a single glob pattern per line. Empty lines are ignored.
+The same is true for lines starting with ``#``, which indicates a comment.
+A ``!`` at the beginning of a line reverses the glob match pattern from an exclusion
+to an explicit inclusion. This makes it possible to exclude all entries in a
+directory except for a few single files/subdirectories.
+Lines ending in ``/`` match only on directories.
+The directory containing the ``.pxarexclude`` file is considered to be the root of
+the given patterns. It is only possible to match files in this directory and its subdirectories.
+
+``\`` is used to escape special glob characters.
+``?`` matches any single character.
+``*`` matches any character, including an empty string.
+``**`` is used to match subdirectories. It can be used to, for example, exclude
+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 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 whether a file is included or
+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.
+Thus, a ``.pxarexclude`` file in an excluded subdirectory will have no effect.
+``.pxarexclude`` files are treated as regular files and will be included in the
+backup archive.
+
+For example, consider the following directory structure:
+
+.. code-block:: console
+
+    # ls -aR folder
+    folder/:
+    .  ..  .pxarexclude  subfolder0  subfolder1
+
+    folder/subfolder0:
+    .  ..  file0  file1  file2  file3  .pxarexclude
+
+    folder/subfolder1:
+    .  ..  file0  file1  file2  file3
+
+The different ``.pxarexclude`` files contain the following:
+
+.. code-block:: console
+
+    # cat folder/.pxarexclude
+    /subfolder0/file1
+    /subfolder1/*
+    !/subfolder1/file2
+
+.. code-block:: console
+
+    # cat folder/subfolder0/.pxarexclude
+    file3
+
+This would exclude ``file1`` and ``file3`` in ``subfolder0`` and all of
+``subfolder1`` except ``file2``.
+
+Restoring this backup will result in:
+
+.. code-block:: console
+
+    ls -aR restored
+    restored/:
+    .  ..  .pxarexclude  subfolder0  subfolder1
+
+    restored/subfolder0:
+    .  ..  file0  file2  .pxarexclude
+
+    restored/subfolder1:
+    .  ..  file2
+
+
+Encryption
+----------
+
+Proxmox Backup supports client-side encryption with AES-256 in GCM_
+mode. To set this up, you first need to create an encryption key:
+
+.. code-block:: console
+
+  # proxmox-backup-client key create my-backup.key
+  Encryption Key Password: **************
+
+The key is password protected by default. If you do not need this
+extra protection, you can also create it without a password:
+
+.. code-block:: console
+
+  # proxmox-backup-client key create /path/to/my-backup.key --kdf none
+
+Having created this key, it is now possible to create an encrypted backup, by
+passing the ``--keyfile`` parameter, with the path to the key file.
+
+.. code-block:: console
+
+  # proxmox-backup-client backup etc.pxar:/etc --keyfile /path/to/my-backup.key
+  Password: *********
+  Encryption Key Password: **************
+  ...
+
+.. Note:: If you do not specify the name of the backup key, the key will be
+  created in the default location
+  ``~/.config/proxmox-backup/encryption-key.json``. ``proxmox-backup-client``
+  will also search this location by default, in case the ``--keyfile``
+  parameter is not specified.
+
+You can avoid entering the passwords by setting the environment
+variables ``PBS_PASSWORD`` and ``PBS_ENCRYPTION_PASSWORD``.
+
+
+Using a master key to store and recover encryption keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also use ``proxmox-backup-client key`` to create an RSA public/private
+key pair, which can be used to store an encrypted version of the symmetric
+backup encryption key alongside each backup and recover it later.
+
+To set up a master key:
+
+1. Create an encryption key for the backup:
+
+   .. code-block:: console
+
+     # proxmox-backup-client key create
+     creating default key at: "~/.config/proxmox-backup/encryption-key.json"
+     Encryption Key Password: **********
+     ...
+
+   The resulting file will be saved to ``~/.config/proxmox-backup/encryption-key.json``.
+
+2. Create an RSA public/private key pair:
+
+   .. code-block:: console
+
+     # proxmox-backup-client key create-master-key
+     Master Key Password: *********
+     ...
+
+   This will create two files in your current directory, ``master-public.pem``
+   and ``master-private.pem``.
+
+3. Import the newly created ``master-public.pem`` public certificate, so that
+   ``proxmox-backup-client`` can find and use it upon backup.
+
+   .. code-block:: console
+
+     # proxmox-backup-client key import-master-pubkey /path/to/master-public.pem
+     Imported public master key to "~/.config/proxmox-backup/master-public.pem"
+
+4. With all these files in place, run a backup job:
+
+   .. code-block:: console
+
+     # proxmox-backup-client backup etc.pxar:/etc
+
+   The key will be stored in your backup, under the name ``rsa-encrypted.key``.
+
+   .. Note:: The ``--keyfile`` parameter can be excluded, if the encryption key
+     is in the default path. If you specified another path upon creation, you
+     must pass the ``--keyfile`` parameter.
+
+5. To test that everything worked, you can restore the key from the backup:
+
+   .. code-block:: console
+
+     # proxmox-backup-client restore /path/to/backup/ rsa-encrypted.key /path/to/target
+
+   .. Note:: You should not need an encryption key to extract this file. However, if
+     a key exists at the default location
+     (``~/.config/proxmox-backup/encryption-key.json``) the program will prompt
+     you for an encryption key password. Simply moving ``encryption-key.json``
+     out of this directory will fix this issue.
+
+6. Then, use the previously generated master key to decrypt the file:
+
+   .. code-block:: console
+
+     # openssl rsautl -decrypt -inkey master-private.pem -in rsa-encrypted.key -out /path/to/target
+     Enter pass phrase for ./master-private.pem: *********
+
+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. In preparation for the worst case scenario,
+  you should consider keeping a paper copy of this key locked away in
+  a safe place.
+
+
+Restoring Data
+--------------
+
+The regular creation of backups is a necessary step to avoiding data
+loss. More importantly, however, is the restoration. It is good practice to perform
+periodic recovery tests to ensure that you can access the data in
+case of problems.
+
+First, you need to find the snapshot which you want to restore. The snapshot
+command provides a list of all the snapshots on the server:
+
+.. code-block:: console
+
+  # proxmox-backup-client snapshots
+  ┌────────────────────────────────┬─────────────┬────────────────────────────────────┐
+  │ snapshot                       │        size │ files                              │
+  ╞════════════════════════════════╪═════════════╪════════════════════════════════════╡
+  │ host/elsa/2019-12-03T09:30:15Z │ 51788646825 │ root.pxar catalog.pcat1 index.json │
+  ├────────────────────────────────┼─────────────┼────────────────────────────────────┤
+  │ host/elsa/2019-12-03T09:35:01Z │ 51790622048 │ root.pxar catalog.pcat1 index.json │
+  ├────────────────────────────────┼─────────────┼────────────────────────────────────┤
+  ...
+
+You can inspect the catalog to find specific files.
+
+.. code-block:: console
+
+  # proxmox-backup-client catalog dump host/elsa/2019-12-03T09:35:01Z
+  ...
+  d "./root.pxar.didx/etc/cifs-utils"
+  l "./root.pxar.didx/etc/cifs-utils/idmap-plugin"
+  d "./root.pxar.didx/etc/console-setup"
+  ...
+
+The restore command lets you restore a single archive from the
+backup.
+
+.. code-block:: console
+
+  # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z root.pxar /target/path/
+
+To get the contents of any archive, you can restore the ``index.json`` file in the
+repository to the target path '-'. This will dump the contents to the standard output.
+
+.. code-block:: console
+
+  # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z index.json -
+
+
+Interactive Restores
+~~~~~~~~~~~~~~~~~~~~
+
+If you only want to restore a few individual files, it is often easier
+to use the interactive recovery shell.
+
+.. code-block:: console
+
+  # proxmox-backup-client catalog shell host/elsa/2019-12-03T09:35:01Z root.pxar
+  Starting interactive shell
+  pxar:/ > ls
+  bin        boot       dev        etc        home       lib        lib32
+  ...
+
+The interactive recovery shell is a minimal command line interface that
+utilizes the metadata stored in the catalog to quickly list, navigate and
+search files in a file archive.
+To restore files, you can select them individually or match them with a glob
+pattern.
+
+Using the catalog for navigation reduces the overhead considerably because only
+the catalog needs to be downloaded and, optionally, decrypted.
+The actual chunks are only accessed if the metadata in the catalog is not enough
+or for the actual restore.
+
+Similar to common UNIX shells ``cd`` and ``ls`` are the commands used to change
+working directory and list directory contents in the archive.
+``pwd`` shows the full path of the current working directory with respect to the
+archive root.
+
+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:
+
+.. code-block:: console
+
+  pxar:/ > find etc/**/*.txt --select
+  "/etc/X11/rgb.txt"
+  pxar:/ > list-selected
+  etc/**/*.txt
+  pxar:/ > restore-selected /target/path
+  ...
+
+This will find and print all files ending in ``.txt`` located in ``etc/`` or a
+subdirectory and add the corresponding pattern to the list for subsequent restores.
+``list-selected`` shows these patterns and ``restore-selected`` finally restores
+all files in the archive matching the patterns to ``/target/path`` on the local
+host. This will scan the whole archive.
+
+With ``restore /target/path`` you can restore the sub-archive given by the current
+working directory to the local target path ``/target/path`` on your host.
+By additionally passing a glob pattern with ``--pattern <glob>``, the restore is
+further limited to files matching the pattern.
+For example:
+
+.. code-block:: console
+
+  pxar:/ > cd /etc/
+  pxar:/etc/ > restore /target/ --pattern **/*.conf
+  ...
+
+The above will scan trough 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/mountpoint
+  # ls /mnt/mountpoint
+  bin   dev  home  lib32  libx32      media  opt   root  sbin  sys  usr
+  boot  etc  lib   lib64  lost+found  mnt    proc  run   srv   tmp  var
+
+This allows you to access the full contents of the archive in a seamless manner.
+
+.. note:: As the FUSE connection needs to fetch and decrypt chunks from the
+    backup server's datastore, this can cause some additional network and CPU
+    load on your host, depending on the operations you perform on the mounted
+    filesystem.
+
+To unmount the filesystem use the ``umount`` command on the mountpoint:
+
+.. code-block:: console
+
+  # 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
+and responds with a ticket that is valid for two hours. The client
+tool automatically stores that ticket and uses it for further requests
+to this server.
+
+You can also manually trigger this login/logout using the login and
+logout commands:
+
+.. code-block:: console
+
+  # proxmox-backup-client login
+  Password: **********
+
+To remove the ticket, issue a logout:
+
+.. code-block:: console
+
+  # proxmox-backup-client logout
+
+
+.. _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>
+
+
+.. caution:: This command removes all archives in this backup
+   snapshot. They will be inaccessible and unrecoverable.
+
+
+Although manual removal is sometimes required, the ``prune``
+command is normally used to systematically delete older backups. Prune lets
+you specify which backup snapshots you want to keep. The
+following retention options are available:
+
+``--keep-last <N>``
+  Keep the last ``<N>`` backup snapshots.
+
+``--keep-hourly <N>``
+  Keep backups for the last ``<N>`` hours. If there is more than one
+  backup for a single hour, only the latest is kept.
+
+``--keep-daily <N>``
+  Keep backups for the last ``<N>`` days. If there is more than one
+  backup for a single day, only the latest is kept.
+
+``--keep-weekly <N>``
+  Keep backups for the last ``<N>`` weeks. If there is more than one
+  backup for a single week, only the latest is kept.
+
+  .. note:: Weeks start on Monday and end on Sunday. The software
+     uses the `ISO week date`_ system and handles weeks at
+     the end of the year correctly.
+
+``--keep-monthly <N>``
+  Keep backups for the last ``<N>`` months. If there is more than one
+  backup for a single month, only the latest is kept.
+
+``--keep-yearly <N>``
+  Keep backups for the last ``<N>`` years. If there is more than one
+  backup for a single year, only the latest is kept.
+
+The retention options are processed in the order given above. Each option
+only covers backups within its time period. The next option does not take care
+of already covered backups. It will only consider older backups.
+
+Unfinished and incomplete backups will be removed by the prune command unless
+they are newer than the last successful backup. In this case, the last failed
+backup is retained.
+
+.. code-block:: console
+
+  # proxmox-backup-client prune <group> --keep-daily 7 --keep-weekly 4 --keep-monthly 3
+
+
+You can use the ``--dry-run`` option to test your settings. This only
+shows the list of existing snapshots and what actions prune would take.
+
+.. code-block:: console
+
+  # proxmox-backup-client prune host/elsa --dry-run --keep-daily 1 --keep-weekly 3
+  ┌────────────────────────────────┬──────┐
+  │ snapshot                       │ keep │
+  ╞════════════════════════════════╪══════╡
+  │ host/elsa/2019-12-04T13:20:37Z │    1 │
+  ├────────────────────────────────┼──────┤
+  │ host/elsa/2019-12-03T09:35:01Z │    0 │
+  ├────────────────────────────────┼──────┤
+  │ host/elsa/2019-11-22T11:54:47Z │    1 │
+  ├────────────────────────────────┼──────┤
+  │ host/elsa/2019-11-21T12:36:25Z │    0 │
+  ├────────────────────────────────┼──────┤
+  │ host/elsa/2019-11-10T10:42:20Z │    1 │
+  └────────────────────────────────┴──────┘
+
+.. note:: Neither the ``prune`` command nor the ``forget`` command free space
+   in the chunk-store. The chunk-store still contains the data blocks. To free
+   space you need to perform :ref:`garbage-collection`.
+
+
+.. _garbage-collection:
+
+Garbage Collection
+------------------
+
+The ``prune`` command removes only the backup index files, not the data
+from the datastore. This task is left to the garbage collection
+command. It is recommended to carry out garbage collection on a regular basis.
+
+The garbage collection works in two phases. In the first phase, all
+data blocks that are still in use are marked. In the second phase,
+unused data blocks are removed.
+
+.. note:: This command needs to read all existing backup index files
+  and touches the complete chunk-store. This can take a long time
+  depending on the number of chunks and the speed of the underlying
+  disks.
+
+.. note:: The garbage collection will only remove chunks that haven't been used
+   for at least one day (exactly 24h 5m). This grace period is necessary because
+   chunks in use are marked by touching the chunk which updates the ``atime``
+   (access time) property. Filesystems are mounted with the ``relatime`` option
+   by default. This results in a better performance by only updating the
+   ``atime`` property if the last access has been at least 24 hours ago. The
+   downside is, that touching a chunk within these 24 hours will not always
+   update its ``atime`` property.
+
+   Chunks in the grace period will be logged at the end of the garbage
+   collection task as *Pending removals*.
+
+.. code-block:: console
+
+  # proxmox-backup-client garbage-collect
+  starting garbage collection on store store2
+  Start GC phase1 (mark used chunks)
+  Start GC phase2 (sweep unused chunks)
+  percentage done: 1, chunk count: 219
+  percentage done: 2, chunk count: 453
+  ...
+  percentage done: 99, chunk count: 21188
+  Removed bytes: 411368505
+  Removed chunks: 203
+  Original data bytes: 327160886391
+  Disk bytes: 52767414743 (16 %)
+  Disk chunks: 21221
+  Average chunk size: 2486565
+  TASK OK
+
+
+.. todo:: howto run garbage-collection at regular intervals (cron)
+
+Benchmarking
+------------
+
+The backup client also comes with a benchmarking tool. This tool measures
+various metrics relating to compression and encryption speeds. You can run a
+benchmark using the ``benchmark`` subcommand of ``proxmox-backup-client``:
+
+.. code-block:: console
+
+  # proxmox-backup-client benchmark
+  Uploaded 656 chunks in 5 seconds.
+  Time per request: 7659 microseconds.
+  TLS speed: 547.60 MB/s
+  SHA256 speed: 585.76 MB/s
+  Compression speed: 1923.96 MB/s
+  Decompress speed: 7885.24 MB/s
+  AES256/GCM speed: 3974.03 MB/s
+  ┌───────────────────────────────────┬─────────────────────┐
+  │ Name                              │ Value               │
+  ╞═══════════════════════════════════╪═════════════════════╡
+  │ TLS (maximal backup upload speed) │ 547.60 MB/s (93%)   │
+  ├───────────────────────────────────┼─────────────────────┤
+  │ SHA256 checksum computation speed │ 585.76 MB/s (28%)   │
+  ├───────────────────────────────────┼─────────────────────┤
+  │ ZStd level 1 compression speed    │ 1923.96 MB/s (89%)  │
+  ├───────────────────────────────────┼─────────────────────┤
+  │ ZStd level 1 decompression speed  │ 7885.24 MB/s (98%)  │
+  ├───────────────────────────────────┼─────────────────────┤
+  │ AES256 GCM encryption speed       │ 3974.03 MB/s (104%) │
+  └───────────────────────────────────┴─────────────────────┘
+
+.. note:: The percentages given in the output table correspond to a
+  comparison against a Ryzen 7 2700X. The TLS test connects to the
+  local host, so there is no network involved.
+
+You can also pass the ``--output-format`` parameter to output stats in ``json``,
+rather than the default table format.
+
+

docs/calendarevents.rst

@@ -0,0 +1,100 @@
+
+.. _calendar-events:
+
+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

@@ -12,7 +12,7 @@ Command Line Tools
 .. 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
 

docs/conf.py

@@ -17,10 +17,28 @@
 # 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
+# * avoid space between lines to nicely format utf8 tables
+
+from sphinx.highlighting import PygmentsBridge
+from pygments.formatters.latex import LatexFormatter
+
+class CustomLatexFormatter(LatexFormatter):
+    def __init__(self, **options):
+        super(CustomLatexFormatter, self).__init__(**options)
+        self.verboptions = r"formatcom=\footnotesize\relax\let\strut\empty"
+
+PygmentsBridge.latex_formatter = CustomLatexFormatter
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -30,7 +48,10 @@
 # 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.todo", "proxmox-scanrefs"]
+
+todo_link_only = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -53,7 +74,7 @@ rst_epilog = epilog_file.read()
 
 # General information about the project.
 project = 'Proxmox Backup'
-copyright = '2019, Proxmox Support Team'
+copyright = '2019-2020, Proxmox Server Solutions GmbH'
 author = 'Proxmox Support Team'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -61,9 +82,11 @@ author = 'Proxmox Support Team'
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+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 = '1.0-1'
+release = vstr(os.getenv('DEB_VERSION'))
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -74,12 +97,10 @@ 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.
@@ -92,7 +113,7 @@ exclude_patterns = [
     'pxar/man1.rst',
     'epilog.rst',
     'pbs-copyright.rst',
-    'sysadmin.rst',
+    'local-zfs.rst'
     'package-repositories.rst',
 ]
 
@@ -125,7 +146,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 ----------------------------------------------
@@ -133,13 +154,51 @@ 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',
+    },
+
+    '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 = []
@@ -156,7 +215,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
@@ -186,10 +245,6 @@ html_static_path = ['_static']
 #
 # 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.
 #
@@ -209,7 +264,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.
 #
@@ -251,14 +306,24 @@ htmlhelp_basename = 'ProxmoxBackupdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
+latex_engine = 'xelatex'
+
 latex_elements = {
+    'fontenc': '\\usepackage{fontspec}',
+
      # The paper size ('letterpaper' or 'a4paper').
      #
      'papersize': 'a4paper',
 
      # The font size ('10pt', '11pt' or '12pt').
      #
-     'pointsize': '12pt',
+     'pointsize': '10pt',
+
+    'fontpkg': r'''
+\setmainfont{Open Sans}
+\setsansfont{Lato}
+\setmonofont{DejaVu Sans Mono}
+''',
 
      # Additional stuff for the LaTeX preamble.
      #

docs/custom.css

@@ -0,0 +1,52 @@
+div.sphinxsidebar {
+    height: calc(100% - 20px);
+    overflow: auto;
+}
+
+h1.logo-name {
+    font-size: 24px;
+}
+
+div.body img {
+    width: 250px;
+}
+pre {
+    padding: 5px 10px;
+}
+
+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 form.search {
+    margin-bottom: 5px;
+}
+
+div.sphinxsidebar h3 {
+    width: 100%;
+}
+
+div.sphinxsidebar h1.logo-name {
+    display: none;
+}
+@media screen and (max-width: 875px) {
+    div.sphinxsidebar p.logo {
+        display: initial;
+    }
+    div.sphinxsidebar h1.logo-name {
+        display: block;
+    }
+    div.sphinxsidebar span {
+        color: #AAA;
+    }
+    ul li.toctree-l1 > a {
+        color: #FFF;
+    }
+}

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,71 @@
+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) | tba           | 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 supports client-side encryption, meaning your data is
+encrypted before it reaches the server. Thus, in the event that an attacker
+gains access to the server, they will not be able to read the data.
+
+.. note:: Encryption is not enabled by default. To set up encryption, see the
+  `Encryption
+  <https://pbs.proxmox.com/docs/administration-guide.html#encryption>`_ section
+  of the Proxmox Backup Server Administration Guide.
+
+
+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/glossary.rst

@@ -5,24 +5,23 @@ Glossary
 
    `Virtual machine`_
 
-      A Virtual machine is a program that can execute an entire
+      A virtual machine is a program that can execute an entire
-      operatin system inside an emulated hardware environment.
+      operating system inside an emulated hardware environment.
 
    `Container`_
 
-      A Container is an isolated user space. Programs runs directly on
+      A container is an isolated user space. Programs run directly on
-      the hosts kernel, but with limited access to the host resources.
+      the host's kernel, but with limited access to the host resources.
 
    Datastore
 
-      A place to store backups. The current implemenation is
+      A place to store backups. A directory which contains the backup data.
-      file-system based, so this refers to a directory containing the
+      The current implementation is file-system based.
-      backup data.
 
    `Rust`_
 
       Rust is a new, fast and memory-efficient system programming
-      language, with no runtime or garbage collector. Rust’s rich type
+      language. It has no runtime or garbage collector. Rust’s rich type
       system and ownership model guarantee memory-safety and
       thread-safety. I can eliminate many classes of bugs
       at compile-time.
@@ -31,11 +30,9 @@ Glossary
 
       Is a tool that makes it easy to create intelligent and
       beautiful documentation. It was originally created for the
-      Python documentation, and it has excellent facilities for the
+      documentation of the Python programming language. It has excellent facilities for the
       documentation of software projects in a range of languages.
 
-
-
    `reStructuredText`_
 
       Is an easy-to-read, what-you-see-is-what-you-get plaintext
@@ -44,8 +41,13 @@ Glossary
    `FUSE`
 
       Filesystem in Userspace (`FUSE <https://en.wikipedia.org/wiki/Filesystem_in_Userspace>`_)
-      defines an interface which allows to implement a filesystem in
+      defines an interface which makes it possible to implement a filesystem in
       userspace as opposed to implementing it in the kernel. The fuse
-      kernel driver handles filesystem requests and sends them to an
+      kernel driver handles filesystem requests and sends them to a
-      userspace application for reply.
+      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,135 @@
+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
+  :width: 250
+  :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
+  :width: 250
+  :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, 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:
+
+* **User Management**: Add users and manage accounts
+* **Permissions**: Manage permissions for various users
+* **Remotes**: Add, edit and remove remotes (see :term:`Remote`)
+* **Sync Jobs**: Manage and run sync jobs to remotes
+* **Subscription**: Upload a subscription key and view subscription status
+
+
+Administration
+^^^^^^^^^^^^^^
+
+.. image:: images/screenshots/pbs-gui-administration-serverstatus.png
+  :width: 250
+  :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
+  :width: 250
+  :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 
+
+
+Datastore
+^^^^^^^^^
+
+.. image:: images/screenshots/pbs-gui-datastore.png
+  :width: 250
+  :align: right
+  :alt: Datastore Configuration
+
+The Datastore section provides an interface for creating and managing
+datastores. It contains a subsection for each datastore on the system, in
+which you can use the top panel to view:
+
+* **Content**: Information on the datastore's backup groups and their respective
+  contents
+* **Statistics**: Usage statistics for the datastore
+* **Permissions**: View and manage permissions for the datastore

docs/index.rst

@@ -1,19 +1,20 @@
 .. Proxmox Backup documentation master file
 
-Welcome to Proxmox Backup's documentation!
+Welcome to the Proxmox Backup documentation!
-==========================================
+============================================
+| Copyright (C) 2019-2020 Proxmox Server Solutions GmbH
+| Version |version| -- |today|
 
-Copyright (C) 2019 Proxmox Server Solutions GmbH
+Permission is granted to copy, distribute and/or modify this document under the
+terms of the GNU Free Documentation License, Version 1.3 or any later version
+published by the Free Software Foundation; with no Invariant Sections, no
+Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included
+in the section entitled "GNU Free Documentation License".
 
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
-copy of the license is included in the section entitled "GNU Free
-Documentation License".
 
-.. todolist::
+.. only:: html
 
+ A `PDF` version of the documentation is `also available here <./proxmox-backup.pdf>`_
 
 .. toctree::
    :maxdepth: 3
@@ -21,7 +22,18 @@ Documentation License".
 
    introduction.rst
    installation.rst
-   administration-guide.rst
+   terminology.rst
+   gui.rst
+   storage.rst
+   network-management.rst
+   user-management.rst
+   managing-remotes.rst
+   maintenance.rst
+   backup-client.rst
+   pve-integration.rst
+   pxar-tool.rst
+   sysadmin.rst
+   faq.rst
 
 .. raw:: latex
 
@@ -34,8 +46,18 @@ Documentation License".
    command-syntax.rst
    file-formats.rst
    backup-protocol.rst
+   calendarevents.rst
    glossary.rst
    GFDL.rst
 
-* :ref:`genindex`
+.. only:: html and devbuild
 
+    .. toctree::
+       :maxdepth: 2
+       :hidden:
+       :caption: Developer Appendix
+
+       todos.rst
+
+
+.. # * :ref:`genindex`

docs/installation.rst

@@ -1,55 +1,52 @@
 Installation
 ============
 
-`Proxmox Backup`_ is split into a server part and a client part. The
+`Proxmox Backup`_ is split into a server and client part. The server part
-server part comes with it's own graphical installer, but we also
+can either be installed with a graphical installer or on top of
-ship Debian_ package repositories, so you can easily install those
+Debian_ from the provided package repository.
-packages on any Debian_ based system.
+
+.. include:: system-requirements.rst
 
 .. include:: package-repositories.rst
 
-
 Server installation
 -------------------
 
-The backup server stores the actual backup data, but also provides a
+The backup server stores the actual backed up data and provides a web based GUI
-web based GUI for various management tasks, for example disk
+for various management tasks such as disk management.
-management.
 
 .. note:: You always need a backup server. It is not possible to use
    `Proxmox Backup`_ without the server part.
 
-The server is based on Debian, therefore the disk image (ISO file) provided
+The disk image (ISO file) provided by Proxmox includes a complete Debian system
-by us includes a complete Debian system ("buster" for version 1.x) as
+("buster" for version 1.x) as well as all necessary packages for the `Proxmox Backup`_ server.
-well as all necessary backup packages.
 
-Using the installer will guide you through the setup, allowing
+The installer will guide you through the setup process and allow
 you to partition the local disk(s), apply basic system configurations
-(e.g. timezone, language, network) and install all required packages.
+(e.g. timezone, language, network), and install all required packages.
-Using the provided ISO will get you started in just a few minutes,
+The provided ISO will get you started in just a few minutes, and is the
-that's why we recommend this method for new and existing users.
+recommended method for new and existing users.
 
 Alternatively, `Proxmox Backup`_ server can be installed on top of an
 existing Debian system.
 
-Using the `Proxmox Backup`_ Installer
+Install `Proxmox Backup`_ with the Installer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can download the ISO from |DOWNLOADS|.
+Download the ISO from |DOWNLOADS|.
 It includes the following:
 
+* The `Proxmox Backup`_ server installer, which partitions the local
+  disk(s) with ext4, ext3, xfs or ZFS, and installs the operating
+  system
+
 * Complete operating system (Debian Linux, 64-bit)
 
-* The `Proxmox Backup`_ server installer, which partitions the local
+* Our Linux kernel with ZFS support
-  disk(s) with ext4, ext3, xfs or ZFS and installs the operating
-  system.
 
-* Our Linux kernel with ZFS support.
+* Complete tool-set to administer backups and all necessary resources
 
-* Complete toolset for administering backups and all necessary
+* Web based GUI management interface
-  resources
-
-* Web based management interface for using the toolset
 
 .. note:: During the installation process, the complete server
    is used by default and all existing data is removed.
@@ -58,8 +55,8 @@ It includes the following:
 Install `Proxmox Backup`_ server on Debian
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Proxmox ships as a set of Debian packages, so you can install it on
+Proxmox ships as a set of Debian packages which can be installed on top of a
-top of a standard Debian installation.  After configuring the
+standard Debian installation. After configuring the
 :ref:`sysadmin_package_repositories`, you need to run:
 
 .. code-block:: console
@@ -67,7 +64,7 @@ top of a standard Debian installation.  After configuring the
   # apt-get update
   # apt-get install proxmox-backup-server
 
-Above code keeps the current (Debian) kernel and installs a minimal
+The commands above keep the current (Debian) kernel and install a minimal
 set of required packages.
 
 If you want to install the same set of packages as the installer
@@ -78,16 +75,18 @@ does, please use the following:
   # apt-get update
   # apt-get install proxmox-backup
 
-This installs all required packages, the Proxmox kernel with ZFS_
+This will install all required packages, the Proxmox kernel with ZFS_
-support, and a set of commonly useful packages.
+support, and a set of common and useful packages.
 
-Installing on top of an existing Debian_ installation looks easy, but
+.. caution:: Installing `Proxmox Backup`_ on top of an existing Debian_
-it presumes that you have correctly installed the base system, and you
+  installation looks easy, but it assumes that the base system and local
-know how you want to configure and use the local storage. Network
+  storage have been set up correctly. In general this is not trivial, especially
-configuration is also completely up to you.
+  when LVM_ or ZFS_ is used. The network configuration is completely up to you
+  as well.
 
-In general, this is not trivial, especially when you use LVM_ or
+.. note:: You can access the web interface of the Proxmox Backup Server with
-ZFS_.
+  your web browser, using HTTPS on port 8007. For example at
+ ``https://<ip-or-dns-name>:8007``
 
 Install Proxmox Backup server on `Proxmox VE`_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -101,9 +100,13 @@ After configuring the
   # apt-get install proxmox-backup-server
 
 .. caution:: Installing the backup server directly on the hypervisor
-   is not recommended. It is more secure to use a separate physical
+   is not recommended. It is safer to use a separate physical
-   server to store backups. If the hypervisor server fails, you can
+   server to store backups. Should the hypervisor server fail, you can
-   still access your backups.
+   still access the backups.
+
+.. note::
+  You can access the web interface of the Proxmox Backup Server with your web
+  browser, using HTTPS on port 8007. For example at ``https://<ip-or-dns-name>:8007``
 
 Client installation
 -------------------
@@ -111,8 +114,8 @@ Client installation
 Install `Proxmox Backup`_ client on Debian
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Proxmox ships as a set of Debian packages, so you can install it on
+Proxmox ships as a set of Debian packages to be installed on
-top of a standard Debian installation.  After configuring the
+top of a standard Debian installation. After configuring the
 :ref:`sysadmin_package_repositories`, you need to run:
 
 .. code-block:: console

docs/introduction.rst

@@ -1,120 +1,171 @@
 Introduction
 ============
 
-This documentationm is written in :term:`reStructuredText` and formatted with :term:`Sphinx`.
+What is Proxmox Backup Server
+-----------------------------
 
+Proxmox Backup Server is an enterprise-class, client-server backup software
+package that backs up :term:`virtual machine`\ s, :term:`container`\ s, and
+physical hosts. It is specially optimized for the `Proxmox Virtual Environment`_
+platform and allows you to back up your data securely, even between remote
+sites, providing easy management with a web-based user interface.
 
-What is Proxmox Backup
+Proxmox Backup Server supports deduplication, compression, and authenticated
-----------------------
+encryption (AE_). Using :term:`Rust` as the implementation language guarantees high
+performance, low resource usage, and a safe, high-quality codebase.
 
-Proxmox Backup is an enterprise class client-server backup software,
+It features strong client-side encryption. Thus, it's possible to
-specially optimized for `Proxmox Virtual Environment`_ to backup
+backup data to targets that are not fully trusted.
-:term:`virtual machine`\ s and :term:`container`\ s. It is also
-possible to backup physical hosts.
-
-It supports deduplication, compression and authenticated encryption
-(AE_). Using :term:`Rust` as implementation language guarantees high
-performance, low resource usage, and a safe, high quality code base.
-
-Encryption is done at the client side. This makes backups to not fully
-trusted targets possible.
 
 
 Architecture
 ------------
 
-Proxmox Backup uses a `Client-server model`_. The server is
+Proxmox Backup Server uses a `client-server model`_. The server stores the
-responsible to store the backup data, and provides an API to create
+backup data and provides an API to create and manage datastores. With the
-backups and restore data. It is also possible to manage disks and
+API, it's also possible to manage disks and other server-side resources.
-other server side resources using this API.
 
-A backup client uses this API to access the backed up data,
+The backup client uses this API to access the backed up data. With the command
-i.e. ``proxmox-backup-client`` is a command line tool to create
+line tool ``proxmox-backup-client`` you can create backups and restore data.
-backups and restore data. We also deliver an integrated client for
+For QEMU_ with `Proxmox Virtual Environment`_ we deliver an integrated client.
-QEMU_ with `Proxmox Virtual Environment`_.
 
-A single backup is allowed to contain several archives. For example,
+A single backup is allowed to contain several archives. For example, when you
-when you backup a :term:`virtual machine`, each disk is stored as a
+backup a :term:`virtual machine`, each disk is stored as a separate archive
-separate archive inside that backup. The VM configuration also gets an
+inside that backup. The VM configuration itself is stored as an extra file.
-extra file. This way, it is easy to access and restore important parts
+This way, it's easy to access and restore only important parts of the backup,
-of the backup, without having to scan the whole backup.
+without the need to scan the whole backup.
 
 
-Main features
+Main Features
 -------------
 
-:Proxmox VE: The `Proxmox Virtual Environment`_ is fully
+:Support for Proxmox VE: The `Proxmox Virtual Environment`_ is fully
-   supported. You can backup :term:`virtual machine`\ s and
+   supported and you can easily backup :term:`virtual machine`\ s and
    :term:`container`\ s.
 
-:GUI: We provide a graphical, web based user interface.
-
-:Deduplication: Incremental backup produces large amounts of duplicate
-   data. The deduplication layer removes that redundancy and makes
-   inkremental backup small and space efficient.
-
-:Data Integrity: The built in `SHA-256`_ checksum algorithm assures the
-   accuracy and consistency of your backups.
-
-:Remote Sync: It is possible to efficently synchronize data to remote
-   sites. Only deltas containing new data are transfered.
-
 :Performance: The whole software stack is written in :term:`Rust`,
-   which provides high speed and memory efficiency.
+   in order to provide high speed and memory efficiency.
 
-:Compression: Ultra fast Zstandard_ compression is able to compress
+:Deduplication: Periodic backups produce large amounts of duplicate
+   data. The deduplication layer avoids redundancy and minimizes the storage
+   space used.
+
+:Incremental backups: Changes between backups are typically low. Reading and
+   sending only the delta reduces the storage and network impact of backups.
+
+:Data Integrity: The built-in `SHA-256`_ checksum algorithm ensures accuracy and
+   consistency in your backups.
+
+:Remote Sync: It is possible to efficiently synchronize data to remote
+   sites. Only deltas containing new data are transferred.
+
+:Compression: The ultra-fast Zstandard_ compression is able to compress
    several gigabytes of data per second.
 
-:Encryption: Backups can be encrypted at client side using AES-256 in
+:Encryption: Backups can be encrypted on the client-side, using AES-256 in
-   GCM_ mode. This authenticated encryption mode (AE_) provides very
+   Galois/Counter Mode (GCM_) mode. This authenticated encryption (AE_) mode
-   high performance on modern hardware.
+   provides very high performance on modern hardware.
 
-:Open Source: No secrets. You have access to the whole source tree.
+:Web interface: Manage the Proxmox Backup Server with the integrated, web-based
+   user interface.
 
-:Support: Commercial support options available from `Proxmox`_.
+:Open Source: No secrets. Proxmox Backup Server is free and open-source
+   software. The source code is licensed under AGPL, v3.
+
+:Support: Enterprise support will be available from `Proxmox`_ once the beta
+   phase is over.
 
 
-Why Backup?
+Reasons for Data Backup?
------------
+------------------------
 
-The primary purpose of backup is to protect against data loss. Data
+The main purpose of a backup is to protect against data loss. Data loss can be
-loss can happen because of faulty hardware, but also by human errors.
+caused by both faulty hardware and human error.
 
-A common mistake is to delete a file or folder which is still
+A common mistake is to accidentally delete a file or folder which is still
-required. Virtualization can amplify this problem, because it is now
+required. Virtualization can even amplify this problem, as deleting a whole
-easy to delete a whole virtual machine by a single button press.
+virtual machine can be as easy as pressing a single button.
 
-Backups can also serve as a toolkit for administrators to temporarily
+For administrators, backups can serve as a useful toolkit for temporarily
-store data. For example, it is common practice to perform full backups
+storing data. For example, it is common practice to perform full backups before
-before installing major software updates. If something goes wrong, you
+installing major software updates. If something goes wrong, you can easily
-can just restore the previous state.
+restore the previous state.
 
-Another reason for backups are legal requirements. Some data must be
+Another reason for backups are legal requirements. Some data, especially
-kept in a safe place for several years so that you can access it if
+business records, must be kept in a safe place for several years by law, so
-required by law.
+that they can be accessed if required.
 
-Data loss can be very costly as it can severely restrict your
+In general, data loss is very costly as it can severely damage your business.
-business. Therefore, make sure that you regularly perform a backup
+Therefore, ensure that you perform regular backups and run restore tests.
-and run restore tests.
 
 
 Software Stack
 --------------
 
-.. todo:: Eplain why we use Rust (and Flutter)
+Proxmox Backup Server consists of multiple components:
-	  
+
+* A server-daemon providing, among other things, a RESTful API, super-fast
+  asynchronous tasks, lightweight usage statistic collection, scheduling
+  events, strict separation of privileged and unprivileged execution
+  environments
+* A JavaScript management web interface
+* A management CLI tool for the server (`proxmox-backup-manager`)
+* A client CLI tool (`proxmox-backup-client`) to access the server easily from
+  any `Linux amd64` environment
+
+Aside from the web interface, everything is written in the Rust programming
+language.
+
+ "The Rust programming language helps you write faster, more reliable software.
+ High-level ergonomics and low-level control are often at odds in programming
+ language design; Rust challenges that conflict. Through balancing powerful
+ technical capacity and a great developer experience, Rust gives you the option
+ to control low-level details (such as memory usage) without all the hassle
+ traditionally associated with such control."
+
+ -- `The Rust Programming Language <https://doc.rust-lang.org/book/ch00-00-introduction.html>`_
+
+.. todo:: further explain the software stack
+
+
+Getting Help
+------------
+
+Community Support Forum
+~~~~~~~~~~~~~~~~~~~~~~~
+
+We always encourage our users to discuss and share their knowledge using the
+`Proxmox Community Forum`_. The forum is moderated by the Proxmox support team.
+The large user base is spread out all over the world. Needless to say that such
+a large forum is a great place to get information.
+
+Mailing Lists
+~~~~~~~~~~~~~
+
+Proxmox Backup Server is fully open-source and contributions are welcome! Here
+is the primary communication channel for developers:
+
+:Mailing list for developers: `PBS Development List`_
+
+Bug Tracker
+~~~~~~~~~~~
+
+Proxmox runs a public bug tracker at `<https://bugzilla.proxmox.com>`_. If an
+issue appears, file your report there. An issue can be a bug as well as a
+request for a new feature or enhancement. The bug tracker helps to keep track
+of the issue and will send a notification once it has been solved.
 
 License
 -------
 
-Copyright (C) 2019 Proxmox Server Solutions GmbH
+Copyright (C) 2019-2020 Proxmox Server Solutions GmbH
 
 This software is written by Proxmox Server Solutions GmbH <support@proxmox.com>
 
-Proxmox Backup is free software: you can redistribute it and/or modify
+Proxmox Backup Server is free and open source software: you can use it,
-it under the terms of the GNU Affero General Public License as
+redistribute it, and/or modify it under the terms of the GNU Affero General
-published by the Free Software Foundation, either version 3 of the
+Public License as published by the Free Software Foundation, either version 3
-License, or (at your option) any later version.
+of the License, or (at your option) any later version.
 
 This program is distributed in the hope that it will be useful, but
 ``WITHOUT ANY WARRANTY``; without even the implied warranty of
@@ -128,5 +179,29 @@ along with this program.  If not, see AGPL3_.
 History
 -------
 
-.. todo:: Add development History of the product
+Backup is, and always was, as central aspect of IT administration.
+The need to recover from data loss is fundamental and increases with
+virtualization.
 
+Not surprisingly, we shipped a backup tool with Proxmox VE from the
+beginning. The tool is called ``vzdump`` and is able to make
+consistent snapshots of running LXC containers and KVM virtual
+machines.
+
+But ``vzdump`` only allowed for full backups. While this is perfect
+for small backups, it becomes a burden for users with large VMs. Both
+backup time and space usage was too large for this case, specially
+when Users want to keep many backups of the same VMs. We need
+deduplication and incremental backups to solve those problems.
+
+Back in October 2018 development started. We had been looking into
+several technologies and frameworks and finally decided to use
+:term:`Rust` as implementation language to provide high speed and
+memory efficiency. The 2018-edition of Rust seemed to be promising and
+useful for our requirements.
+
+In July 2020 we released the first beta version of Proxmox Backup
+Server, followed by a first stable version in November 2020. With the
+support of incremental, fully deduplicated backups, Proxmox Backup
+significantly reduces the network load and saves valuable storage
+space.

docs/local-zfs.rst

@@ -0,0 +1,405 @@
+
+.. _chapter-zfs:
+
+ZFS on Linux
+------------
+
+ZFS is a combined file system and logical volume manager designed by
+Sun Microsystems. There is no need to manually compile ZFS modules - all
+packages are included.
+
+By using ZFS, it's possible to achieve maximum enterprise features with
+low budget hardware, but also high performance systems by leveraging
+SSD caching or even SSD only setups. ZFS can replace cost intense
+hardware raid cards by moderate CPU and memory load combined with easy
+management.
+
+General ZFS advantages
+
+* Easy configuration and management with GUI and CLI.
+* Reliable
+* Protection against data corruption
+* Data compression on file system level
+* Snapshots
+* Copy-on-write clone
+* Various raid levels: RAID0, RAID1, RAID10, RAIDZ-1, RAIDZ-2 and RAIDZ-3
+* Can use SSD for cache
+* Self healing
+* Continuous integrity checking
+* Designed for high storage capacities
+* Asynchronous replication over network
+* Open Source
+* Encryption
+
+Hardware
+~~~~~~~~~
+
+ZFS depends heavily on memory, so you need at least 8GB to start. In
+practice, use as much you can get for your hardware/budget. To prevent
+data corruption, we recommend the use of high quality ECC RAM.
+
+If you use a dedicated cache and/or log disk, you should use an
+enterprise class SSD (e.g. Intel SSD DC S3700 Series). This can
+increase the overall performance significantly.
+
+IMPORTANT: Do not use ZFS on top of hardware controller which has its
+own cache management. ZFS needs to directly communicate with disks. An
+HBA adapter is the way to go, or something like LSI controller flashed
+in ``IT`` mode.
+
+
+ZFS Administration
+~~~~~~~~~~~~~~~~~~
+
+This section gives you some usage examples for common tasks. ZFS
+itself is really powerful and provides many options. The main commands
+to manage ZFS are `zfs` and `zpool`. Both commands come with great
+manual pages, which can be read with:
+
+.. code-block:: console
+
+  # man zpool
+  # man zfs
+
+Create a new zpool
+^^^^^^^^^^^^^^^^^^
+
+To create a new pool, at least one disk is needed. The `ashift` should
+have the same sector-size (2 power of `ashift`) or larger as the
+underlying disk.
+
+.. code-block:: console
+
+  # zpool create -f -o ashift=12 <pool> <device>
+
+Create a new pool with RAID-0
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Minimum 1 disk
+
+.. code-block:: console
+
+  # zpool create -f -o ashift=12 <pool> <device1> <device2>
+
+Create a new pool with RAID-1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Minimum 2 disks
+
+.. code-block:: console
+
+  # zpool create -f -o ashift=12 <pool> mirror <device1> <device2>
+
+Create a new pool with RAID-10
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Minimum 4 disks
+
+.. code-block:: console
+
+  # zpool create -f -o ashift=12 <pool> mirror <device1> <device2> mirror <device3> <device4>
+
+Create a new pool with RAIDZ-1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Minimum 3 disks
+
+.. code-block:: console
+
+  # zpool create -f -o ashift=12 <pool> raidz1 <device1> <device2> <device3>
+
+Create a new pool with RAIDZ-2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Minimum 4 disks
+
+.. code-block:: console
+
+  # zpool create -f -o ashift=12 <pool> raidz2 <device1> <device2> <device3> <device4>
+
+Create a new pool with cache (L2ARC)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to use a dedicated cache drive partition to increase
+the performance (use SSD).
+
+As `<device>` it is possible to use more devices, like it's shown in
+"Create a new pool with RAID*".
+
+.. code-block:: console
+
+  # zpool create -f -o ashift=12 <pool> <device> cache <cache_device>
+
+Create a new pool with log (ZIL)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to use a dedicated cache drive partition to increase
+the performance (SSD).
+
+As `<device>` it is possible to use more devices, like it's shown in
+"Create a new pool with RAID*".
+
+.. code-block:: console
+
+  # zpool create -f -o ashift=12 <pool> <device> log <log_device>
+
+Add cache and log to an existing pool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have a pool without cache and log. First partition the SSD in
+2 partition with `parted` or `gdisk`
+
+.. important:: Always use GPT partition tables.
+
+The maximum size of a log device should be about half the size of
+physical memory, so this is usually quite small. The rest of the SSD
+can be used as cache.
+
+.. code-block:: console
+
+  # zpool add -f <pool> log <device-part1> cache <device-part2>
+
+
+Changing a failed device
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+  # zpool replace -f <pool> <old device> <new device>
+
+
+Changing a failed bootable device
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on how Proxmox Backup was installed it is either using `grub` or `systemd-boot`
+as bootloader.
+
+The first steps of copying the partition table, reissuing GUIDs and replacing
+the ZFS partition are the same. To make the system bootable from the new disk,
+different steps are needed which depend on the bootloader in use.
+
+.. code-block:: console
+
+  # sgdisk <healthy bootable device> -R <new device>
+  # sgdisk -G <new device>
+  # zpool replace -f <pool> <old zfs partition> <new zfs partition>
+
+.. NOTE:: Use the `zpool status -v` command to monitor how far the resilvering process of the new disk has progressed.
+
+With `systemd-boot`:
+
+.. code-block:: console
+
+  # pve-efiboot-tool format <new disk's ESP>
+  # pve-efiboot-tool init <new disk's ESP>
+
+.. NOTE:: `ESP` stands for EFI System Partition, which is setup as partition #2 on
+  bootable disks setup by the {pve} installer since version 5.4. For details, see
+  xref:sysboot_systemd_boot_setup[Setting up a new partition for use as synced ESP].
+
+With `grub`:
+
+Usually `grub.cfg` is located in `/boot/grub/grub.cfg`
+
+.. code-block:: console
+
+  # grub-install <new disk>
+  # grub-mkconfig -o /path/to/grub.cfg
+
+
+Activate E-Mail Notification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ZFS comes with an event daemon, which monitors events generated by the
+ZFS kernel module. The daemon can also send emails on ZFS events like
+pool errors. Newer ZFS packages ship the daemon in a separate package,
+and you can install it using `apt-get`:
+
+.. code-block:: console
+
+  # apt-get install zfs-zed
+
+To activate the daemon it is necessary to edit `/etc/zfs/zed.d/zed.rc` with your
+favorite editor, and uncomment the `ZED_EMAIL_ADDR` setting:
+
+.. code-block:: console
+
+  ZED_EMAIL_ADDR="root"
+
+Please note Proxmox Backup forwards mails to `root` to the email address
+configured for the root user.
+
+IMPORTANT: The only setting that is required is `ZED_EMAIL_ADDR`. All
+other settings are optional.
+
+Limit ZFS Memory Usage
+^^^^^^^^^^^^^^^^^^^^^^
+
+It is good to use at most 50 percent (which is the default) of the
+system memory for ZFS ARC to prevent performance shortage of the
+host. Use your preferred editor to change the configuration in
+`/etc/modprobe.d/zfs.conf` and insert:
+
+.. code-block:: console
+
+  options zfs zfs_arc_max=8589934592
+
+This example setting limits the usage to 8GB.
+
+.. IMPORTANT:: If your root file system is ZFS you must update your initramfs every time this value changes:
+
+.. code-block:: console
+
+  # update-initramfs -u
+
+
+SWAP on ZFS
+^^^^^^^^^^^
+
+Swap-space created on a zvol may generate some troubles, like blocking the
+server or generating a high IO load, often seen when starting a Backup
+to an external Storage.
+
+We strongly recommend to use enough memory, so that you normally do not
+run into low memory situations. Should you need or want to add swap, it is
+preferred to create a partition on a physical disk and use it as swap device.
+You can leave some space free for this purpose in the advanced options of the
+installer. Additionally, you can lower the `swappiness` value. 
+A good value for servers is 10:
+
+.. code-block:: console
+
+  # sysctl -w vm.swappiness=10
+
+To make the swappiness persistent, open `/etc/sysctl.conf` with
+an editor of your choice and add the following line:
+
+.. code-block:: console
+
+  vm.swappiness = 10
+
+.. table:: Linux kernel `swappiness` parameter values
+  :widths:auto
+
+  ====================  ===============================================================
+   Value                Strategy
+  ====================  ===============================================================
+   vm.swappiness = 0    The kernel will swap only to avoid an 'out of memory' condition
+   vm.swappiness = 1    Minimum amount of swapping without disabling it entirely.
+   vm.swappiness = 10   Sometimes recommended to improve performance when sufficient memory exists in a system.
+   vm.swappiness = 60   The default value.
+   vm.swappiness = 100  The kernel will swap aggressively.
+  ====================  ===============================================================
+
+ZFS Compression
+^^^^^^^^^^^^^^^
+
+To activate compression:
+.. code-block:: console
+
+  # zpool set compression=lz4 <pool>
+
+We recommend using the `lz4` algorithm, since it adds very little CPU overhead.
+Other algorithms such as `lzjb` and `gzip-N` (where `N` is an integer `1-9` representing
+the compression ratio, 1 is fastest and 9 is best compression) are also available.
+Depending on the algorithm and how compressible the data is, having compression enabled can even increase
+I/O performance.
+
+You can disable compression at any time with:
+.. code-block:: console
+
+  # zfs set compression=off <dataset>
+
+Only new blocks will be affected by this change.
+
+.. _local_zfs_special_device:
+
+ZFS Special Device
+^^^^^^^^^^^^^^^^^^
+
+Since version 0.8.0 ZFS supports `special` devices. A `special` device in a
+pool is used to store metadata, deduplication tables, and optionally small
+file blocks.
+
+A `special` device can improve the speed of a pool consisting of slow spinning
+hard disks with a lot of metadata changes. For example workloads that involve
+creating, updating or deleting a large number of files will benefit from the
+presence of a `special` device. ZFS datasets can also be configured to store
+whole small files on the `special` device which can further improve the
+performance. Use fast SSDs for the `special` device.
+
+.. IMPORTANT:: The redundancy of the `special` device should match the one of the
+  pool, since the `special` device is a point of failure for the whole pool.
+
+.. WARNING:: Adding a `special` device to a pool cannot be undone!
+
+Create a pool with `special` device and RAID-1:
+
+.. code-block:: console
+
+  # zpool create -f -o ashift=12 <pool> mirror <device1> <device2> special mirror <device3> <device4>
+
+Adding a `special` device to an existing pool with RAID-1:
+
+.. code-block:: console
+
+  # zpool add <pool> special mirror <device1> <device2>
+
+ZFS datasets expose the `special_small_blocks=<size>` property. `size` can be
+`0` to disable storing small file blocks on the `special` device or a power of
+two in the range between `512B` to `128K`. After setting the property new file
+blocks smaller than `size` will be allocated on the `special` device.
+
+.. IMPORTANT:: If the value for `special_small_blocks` is greater than or equal to
+  the `recordsize` (default `128K`) of the dataset, *all* data will be written to
+  the `special` device, so be careful!
+
+Setting the `special_small_blocks` property on a pool will change the default
+value of that property for all child ZFS datasets (for example all containers
+in the pool will opt in for small file blocks).
+
+Opt in for all file smaller than 4K-blocks pool-wide:
+
+.. code-block:: console
+
+  # zfs set special_small_blocks=4K <pool>
+
+Opt in for small file blocks for a single dataset:
+
+.. code-block:: console
+
+  # zfs set special_small_blocks=4K <pool>/<filesystem>
+
+Opt out from small file blocks for a single dataset:
+
+.. code-block:: console
+
+  # zfs set special_small_blocks=0 <pool>/<filesystem>
+
+Troubleshooting
+^^^^^^^^^^^^^^^
+
+Corrupted cachefile
+
+In case of a corrupted ZFS cachefile, some volumes may not be mounted during
+boot until mounted manually later.
+
+For each pool, run:
+
+.. code-block:: console
+
+  # zpool set cachefile=/etc/zfs/zpool.cache POOLNAME
+
+and afterwards update the `initramfs` by running:
+
+.. code-block:: console
+
+  # update-initramfs -u -k all
+
+and finally reboot your node.
+
+Sometimes the ZFS cachefile can get corrupted, and `zfs-import-cache.service`
+doesn't import the pools that aren't present in the cachefile.
+
+Another workaround to this problem is enabling the `zfs-import-scan.service`,
+which searches and imports pools via device scanning (usually slower).

docs/maintenance.rst

@@ -0,0 +1,13 @@
+Maintenance Tasks
+=================
+
+Garbage Collection
+------------------
+
+You can monitor and run :ref:`garbage collection <garbage-collection>` on the
+Proxmox Backup Server using the ``garbage-collection`` subcommand of
+``proxmox-backup-manager``. You can use the ``start`` subcommand to manually start garbage
+collection on an entire datastore and the ``status`` subcommand to see
+attributes relating to the :ref:`garbage collection <garbage-collection>`.
+
+.. todo:: Add section on verification

docs/managing-remotes.rst

@@ -0,0 +1,82 @@
+Managing Remotes
+================
+
+.. _backup_remote:
+
+:term:`Remote`
+--------------
+
+A remote refers to a separate Proxmox Backup Server installation and a user on that
+installation, from which you can `sync` datastores to a local datastore with a
+`Sync Job`. You can configure remotes in the web interface, under **Configuration
+-> Remotes**. Alternatively, you can use the ``remote`` subcommand. The
+configuration information for remotes is stored in the file
+``/etc/proxmox-backup/remote.cfg``.
+
+.. image:: images/screenshots/pbs-gui-remote-add.png
+  :align: right
+  :alt: Add a remote
+
+To add a remote, you need its hostname or IP, a userid and password on the
+remote, and its certificate fingerprint. To get the fingerprint, use the
+``proxmox-backup-manager cert info`` command on the remote, or navigate to
+**Dashboard** in the remote's web interface and select **Show Fingerprint**.
+
+.. code-block:: console
+
+  # proxmox-backup-manager cert info |grep Fingerprint
+  Fingerprint (sha256): 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
+
+Using the information specified above, you can add a remote from the **Remotes**
+configuration panel, or by using the command:
+
+.. code-block:: console
+
+  # proxmox-backup-manager remote create pbs2 --host pbs2.mydomain.example --userid sync@pam --password 'SECRET' --fingerprint 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
+
+Use the ``list``, ``show``, ``update``, ``remove`` subcommands of
+``proxmox-backup-manager remote`` to manage your remotes:
+
+.. code-block:: console
+
+  # proxmox-backup-manager remote update pbs2 --host pbs2.example
+  # proxmox-backup-manager remote list
+  ┌──────┬──────────────┬──────────┬───────────────────────────────────────────┬─────────┐
+  │ name │ host         │ userid   │ fingerprint                               │ comment │
+  ╞══════╪══════════════╪══════════╪═══════════════════════════════════════════╪═════════╡
+  │ pbs2 │ pbs2.example │ sync@pam │64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe │         │
+  └──────┴──────────────┴──────────┴───────────────────────────────────────────┴─────────┘
+  # proxmox-backup-manager remote remove pbs2
+
+
+.. _syncjobs:
+
+Sync Jobs
+---------
+
+.. image:: images/screenshots/pbs-gui-syncjob-add.png
+  :align: right
+  :alt: Add a Sync Job
+
+Sync jobs are configured to pull the contents of a datastore on a **Remote** to
+a local datastore. You can manage sync jobs under **Configuration -> Sync Jobs**
+in the web interface, or using the ``proxmox-backup-manager sync-job`` command.
+The configuration information for sync jobs is stored at
+``/etc/proxmox-backup/sync.cfg``. To create a new sync job, click the add button
+in the GUI, or use the ``create`` subcommand. After creating a sync job, you can
+either start it manually on the GUI or provide it with a schedule (see
+:ref:`calendar-events`) to run regularly.
+
+.. code-block:: console
+
+  # proxmox-backup-manager sync-job create pbs2-local --remote pbs2 --remote-store local --store local --schedule 'Wed 02:30'
+  # proxmox-backup-manager sync-job update pbs2-local --comment 'offsite'
+  # proxmox-backup-manager sync-job list
+  ┌────────────┬───────┬────────┬──────────────┬───────────┬─────────┐
+  │ id         │ store │ remote │ remote-store │ schedule  │ comment │
+  ╞════════════╪═══════╪════════╪══════════════╪═══════════╪═════════╡
+  │ pbs2-local │ local │ pbs2   │ local        │ Wed 02:30 │ offsite │
+  └────────────┴───────┴────────┴──────────────┴───────────┴─────────┘
+  # proxmox-backup-manager sync-job remove pbs2-local
+
+

docs/network-management.rst

@@ -0,0 +1,88 @@
+Network Management
+==================
+
+Proxmox Backup Server provides both a web interface and a command line tool for
+network configuration. You can find the configuration options in the web
+interface under the **Network Interfaces** section of the **Configuration** menu
+tree item. The command line tool is accessed via the ``network`` subcommand.
+These interfaces allow you to carry out some basic network management tasks,
+such as adding, configuring, and removing network interfaces.
+
+.. note:: Any changes made to the network configuration are not
+  applied, until you click on **Apply Configuration** or enter the ``network
+  reload`` command. This allows you to make many changes at once. It also allows
+  you to ensure that your changes are correct before applying them, as making a
+  mistake here can render the server inaccessible over the network.
+
+To get a list of available interfaces, use the following command:
+
+.. code-block:: console
+
+  # proxmox-backup-manager network list
+  ┌───────┬────────┬───────────┬────────┬─────────────┬──────────────┬──────────────┐
+  │ name  │ type   │ autostart │ method │ address     │ gateway      │ ports/slaves │
+  ╞═══════╪════════╪═══════════╪════════╪═════════════╪══════════════╪══════════════╡
+  │ bond0 │ bond   │         1 │ static │ x.x.x.x/x   │ x.x.x.x      │ ens18 ens19  │
+  ├───────┼────────┼───────────┼────────┼─────────────┼──────────────┼──────────────┤
+  │ ens18 │ eth    │         1 │ manual │             │              │              │
+  ├───────┼────────┼───────────┼────────┼─────────────┼──────────────┼──────────────┤
+  │ ens19 │ eth    │         1 │ manual │             │              │              │
+  └───────┴────────┴───────────┴────────┴─────────────┴──────────────┴──────────────┘
+
+.. image:: images/screenshots/pbs-gui-network-create-bond.png
+  :align: right
+  :alt: Add a network interface
+
+To add a new network interface, use the ``create`` subcommand with the relevant
+parameters. For example, you may want to set up a bond, for the purpose of
+network redundancy. The following command shows a template for creating the bond shown
+in the list above:
+
+.. code-block:: console
+
+  # proxmox-backup-manager network create bond0 --type bond --bond_mode active-backup --slaves ens18,ens19 --autostart true --cidr x.x.x.x/x --gateway x.x.x.x
+
+You can make changes to the configuration of a network interface with the
+``update`` subcommand:
+
+.. code-block:: console
+
+  # proxmox-backup-manager network update bond0 --cidr y.y.y.y/y
+
+You can also remove a network interface:
+
+.. code-block:: console
+
+   # proxmox-backup-manager network remove bond0
+
+The pending changes for the network configuration file will appear at the bottom of the
+web interface. You can also view these changes, by using the command:
+
+.. code-block:: console
+
+  # proxmox-backup-manager network changes
+
+If you would like to cancel all changes at this point, you can either click on
+the **Revert** button or use the following command:
+
+.. code-block:: console
+
+  # proxmox-backup-manager network revert
+
+If you are happy with the changes and would like to write them into the
+configuration file, select **Apply Configuration**. The corresponding command
+is:
+
+.. code-block:: console
+
+  # proxmox-backup-manager network reload
+
+.. note:: This command and corresponding GUI button rely on the ``ifreload``
+  command, from the package ``ifupdown2``. This package is included within the
+  Proxmox Backup Server installation, however, you may have to install it yourself,
+  if you have installed Proxmox Backup Server on top of Debian or Proxmox VE.
+
+You can also configure DNS settings, from the **DNS** section
+of **Configuration** or by using the ``dns`` subcommand of
+``proxmox-backup-manager``.
+

docs/package-repositories.rst

@@ -3,102 +3,149 @@
 Debian Package Repositories
 ---------------------------
 
-All Debian based systems use APT_ as package
+All Debian based systems use APT_ as a package management tool. The lists of
-management tool. The list of repositories is defined in
+repositories are defined in ``/etc/apt/sources.list`` and the ``.list`` files found
-``/etc/apt/sources.list`` and ``.list`` files found inside
+in the ``/etc/apt/sources.d/`` directory. Updates can be installed directly
-``/etc/apt/sources.d/``. Updates can be installed directly using
+with the ``apt`` command line tool, or via the GUI.
-the ``apt`` command line tool, or via the GUI.
 
-APT_ ``sources.list`` files list one package repository per line, with
+APT_ ``sources.list`` files list one package repository per line, with the most
-the most preferred source listed first. Empty lines are ignored, and a
+preferred source listed first. Empty lines are ignored and a ``#`` character
-``#`` character anywhere on a line marks the remainder of that line as a
+anywhere on a line marks the remainder of that line as a comment. The
-comment. The information available from the configured sources is
+information available from the configured sources is acquired by ``apt
-acquired by ``apt update``.
+update``.
 
 .. code-block:: sources.list
   :caption: File: ``/etc/apt/sources.list``
-	   
+
   deb http://ftp.debian.org/debian buster main contrib
   deb http://ftp.debian.org/debian buster-updates main contrib
 
   # security updates
   deb http://security.debian.org/debian-security buster/updates main contrib
 
-  
+
 .. FIXME for 7.0: change security update suite to bullseye-security
 
-In addition, Proxmox provides three different package repositories for
+In addition, you need a package repository from Proxmox to get Proxmox Backup updates.
-the backup server binaries.
 
-`Proxmox Backup`_ Enterprise Repository
+During the Proxmox Backup beta phase, only one repository (pbstest) will be
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+available. Once released, an Enterprise repository for production use and a
+no-subscription repository will be provided.
 
-This is the default, stable and recommended repository, available for
+SecureApt
-all `Proxmox Backup`_ subscription users. It contains the most stable packages,
+~~~~~~~~~
-and is suitable for production use. The ``pbs-enterprise`` repository is
-enabled by default:
 
-.. code-block:: sources.list
+The `Release` files in the repositories are signed with GnuPG. APT is using
-  :caption: File: ``/etc/apt/sources.list.d/pbs-enterprise.list``
+these signatures to verify that all packages are from a trusted source.
 
-  deb https://enterprise.proxmox.com/debian/pbs buster pbs-enterprise
+If you install Proxmox Backup Server from an official ISO image, the
+verification key is already installed.
+
+If you install Proxmox Backup Server on top of Debian, download and install the
+key with the following commands:
+
+.. code-block:: console
+
+ # wget http://download.proxmox.com/debian/proxmox-ve-release-6.x.gpg -O /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
+
+Verify the SHA512 checksum afterwards with:
+
+.. code-block:: console
+
+ # sha512sum /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
+
+The output should be:
+
+.. code-block:: console
+
+ acca6f416917e8e11490a08a1e2842d500b3a5d9f322c6319db0927b2901c3eae23cfb5cd5df6facf2b57399d3cfa52ad7769ebdd75d9b204549ca147da52626 /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
+
+and the md5sum:
+
+.. code-block:: console
+
+ # md5sum /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
+
+Here, the output should be:
+
+.. code-block:: console
+
+ f3f6c5a3a67baf38ad178e5ff1ee270c /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
+
+.. comment
+    `Proxmox Backup`_ Enterprise Repository
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    This will be the default, stable, and recommended repository. It is available for
+    all `Proxmox Backup`_ subscription users. It contains the most stable packages,
+    and is suitable for production use. The ``pbs-enterprise`` repository is
+    enabled by default:
+
+    .. note:: During the Proxmox Backup beta phase only one repository (pbstest)
+     will be available.
+
+    .. code-block:: sources.list
+      :caption: File: ``/etc/apt/sources.list.d/pbs-enterprise.list``
+
+      deb https://enterprise.proxmox.com/debian/pbs buster pbs-enterprise
 
 
-As soon as updates are available, the superuser (``root@pam`` user) is
+    To never miss important security fixes, the superuser (``root@pam`` user) is
-notified via email about the available new packages. On the GUI, the
+    notified via email about new packages as soon as they are available. The
-change-log of each package can be viewed (if available), showing all
+    change-log and details of each package can be viewed in the GUI (if available).
-details of the update. So you will never miss important security
-fixes.
 
-Please note that you need a valid subscription key to access this
+    Please note that you need a valid subscription key to access this
-repository. We offer different support levels, and you can find further
+    repository. More information regarding subscription levels and pricing can be
-details at https://www.proxmox.com/en/proxmox-backup/pricing.
+    found at https://www.proxmox.com/en/proxmox-backup/pricing.
 
-.. note:: You can disable this repository by commenting out the above
+    .. note:: You can disable this repository by commenting out the above
-  line using a `#` (at the start of the line). This prevents error
+      line using a `#` (at the start of the line). This prevents error
-  messages if you do not have a subscription key. Please configure the
+      messages if you do not have a subscription key. Please configure the
-  ``pbs-no-subscription`` repository in that case.
+      ``pbs-no-subscription`` repository in that case.
 
 
-`Proxmox Backup`_ No-Subscription Repository
+    `Proxmox Backup`_ No-Subscription Repository
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-As the name suggests, you do not need a subscription key to access
+    As the name suggests, you do not need a subscription key to access
-this repository. It can be used for testing and non-production
+    this repository. It can be used for testing and non-production
-use. Its not recommended to run on production servers, as these
+    use. It is not recommended to use it on production servers, because these
-packages are not always heavily tested and validated.
+    packages are not always heavily tested and validated.
 
-We recommend to configure this repository in ``/etc/apt/sources.list``.
+    We recommend to configure this repository in ``/etc/apt/sources.list``.
 
-.. code-block:: sources.list
+    .. code-block:: sources.list
-  :caption: File: ``/etc/apt/sources.list``
+      :caption: File: ``/etc/apt/sources.list``
 
-  deb http://ftp.debian.org/debian buster main contrib
+      deb http://ftp.debian.org/debian buster main contrib
-  deb http://ftp.debian.org/debian buster-updates main contrib
+      deb http://ftp.debian.org/debian buster-updates main contrib
 
-  # PBS pbs-no-subscription repository provided by proxmox.com,
+      # PBS pbs-no-subscription repository provided by proxmox.com,
-  # NOT recommended for production use
+      # NOT recommended for production use
-  deb http://download.proxmox.com/debian/bps buster pbs-no-subscription
+      deb http://download.proxmox.com/debian/pbs buster pbs-no-subscription
 
-  # security updates
+      # security updates
-  deb http://security.debian.org/debian-security buster/updates main contrib
+      deb http://security.debian.org/debian-security buster/updates main contrib
 
 
-`Proxmox Backup`_ Test Repository
+`Proxmox Backup`_ Beta Repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Finally, there is a repository called ``pbstest``. This one contains the
+During the public beta, there is a repository called ``pbstest``. This one
-latest packages and is heavily used by developers to test new
+contains the latest packages and is heavily used by developers to test new
 features.
 
-.. warning:: the ``pbstest`` repository should (as the name implies)
+.. .. warning:: the ``pbstest`` repository should (as the name implies)
-  only be used for testing new features or bug fixes.
+  only be used to test new features or bug fixes.
 
-As usual, you can configure this using ``/etc/apt/sources.list`` by
+You can access this repository by adding the following line to
-adding the following line:
+``/etc/apt/sources.list``:
 
 .. code-block:: sources.list
   :caption: sources.list entry for ``pbstest``
 
-  deb http://download.proxmox.com/debian/bps buster pbstest
+  deb http://download.proxmox.com/debian/pbs buster pbstest
 
+If you installed Proxmox Backup Server from the official beta ISO, you should
+have this repository already configured in
+``/etc/apt/sources.list.d/pbstest-beta.list``

docs/proxmox-backup-proxy/man1.rst

@@ -24,7 +24,7 @@ This daemon is normally started and managed as ``systemd`` service::
 
  systemctl status proxmox-backup-proxy
 
-For debugging, you can start the daemon in forground using::
+For debugging, you can start the daemon in foreground using::
 
  proxmox-backup-proxy
 

docs/pve-integration.rst

@@ -0,0 +1,49 @@
+.. _pve-integration:
+
+`Proxmox VE`_ Integration
+-------------------------
+
+You need to define a new storage with type 'pbs' on your `Proxmox VE`_
+node. The following example uses ``store2`` as storage name, and
+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
+  # pvesm set store2 --username user1@pbs --password <secret>
+
+.. note:: If you would rather not pass your password as plain text, you can pass
+  the ``--password`` parameter, without any arguments. This will cause the
+  program to prompt you for a password upon entering the command.
+
+If your backup server uses a self signed certificate, you need to add
+the certificate fingerprint to the configuration. You can get the
+fingerprint by running the following command on the backup server:
+
+.. code-block:: console
+
+  # proxmox-backup-manager cert info | grep Fingerprint
+  Fingerprint (sha256): 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
+
+Please add that fingerprint to your configuration to establish a trust
+relationship:
+
+.. code-block:: console
+
+  # pvesm set store2 --fingerprint  64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
+
+After that you should be able to see storage status with:
+
+.. code-block:: console
+
+  # pvesm status --storage store2
+  Name             Type     Status           Total            Used       Available        %
+  store2            pbs     active      3905109820      1336687816      2568422004   34.23%
+
+Having added the PBS datastore to `Proxmox VE`_, you can backup VMs and
+containers in the same way you would for any other storage device within the
+environment (see `PVE Admin Guide: Backup and Restore
+<https://pve.proxmox.com/pve-docs/pve-admin-guide.html#chapter_vzdump>`_.
+
+

docs/pxar-tool.rst

@@ -0,0 +1,5 @@
+pxar Command Line Tool
+======================
+
+.. include:: pxar/description.rst
+

docs/pxar/description.rst

@@ -1,15 +1,15 @@
 Description
 ^^^^^^^^^^^
 
-``pxar`` is a command line utility used to create and manipulate archives in the
+``pxar`` is a command line utility to create and manipulate archives in the
 :ref:`pxar-format`.
 It is inspired by `casync file archive format
 <http://0pointer.net/blog/casync-a-tool-for-distributing-file-system-images.html>`_,
-which has a similar use-case.
+which caters to a similar use-case.
-The ``.pxar`` format is adapted to fulfill the specific needs of the proxmox
+The ``.pxar`` format is adapted to fulfill the specific needs of the Proxmox
-backup server, for example efficient storage of hardlinks.
+Backup Server, for example, efficient storage of hardlinks.
 The format is designed to reduce storage space needed on the server by achieving
-high de-duplication.
+a high level of deduplication.
 
 Creating an Archive
 ^^^^^^^^^^^^^^^^^^^
@@ -18,56 +18,55 @@ Run the following command to create an archive of a folder named ``source``:
 
 .. code-block:: console
 
-    # pxar create archive.pxar source
+    # pxar create archive.pxar /path/to/source
 
-This will create a new archive called ``archive.pxar`` from the contents of the
+This will create a new archive called ``archive.pxar`` with the contents of the
 ``source`` folder.
 
 .. NOTE:: ``pxar`` will not overwrite any existing archives. If an archive with
     the same name is already present in the target folder, the creation will
     fail.
 
-By default, ``pxar`` will skip certain mountpoints and not follow device
+By default, ``pxar`` will skip certain mountpoints and will not follow device
 boundaries. This design decision is based on the primary use case of creating
-archives for backups, where it makes no sense to store the content of certain
+archives for backups. It makes sense to not back up the contents of certain
 temporary or system specific files.
-In order to alter this behavior and follow device boundaries, use the
+To alter this behavior and follow device boundaries, use the
 ``--all-file-systems`` flag.
 
 It is possible to exclude certain files and/or folders from the archive by
-passing glob match patterns as additional parameters. Whenever a file is matched
+passing the ``--exclude`` parameter with ``gitignore``\-style match patterns.
-by one of the patterns, you will get a warning saying that this file is skipped
-and therefore not included in the archive.
 
 For example, you can exclude all files ending in ``.txt`` from the archive
 by running:
 
 .. code-block:: console
 
-    # pxar create archive.pxar source '**/*.txt'
+    # pxar create archive.pxar /path/to/source --exclude '**/*.txt'
 
 Be aware that the shell itself will try to expand all of the glob patterns before
 invoking ``pxar``.
 In order to avoid this, all globs have to be quoted correctly.
 
-It is also possible to pass a list of match pattern to fulfill more complex
+It is possible to pass the ``--exclude`` parameter multiple times, in order to
-file exclusion/inclusion behavior, although it is recommended to use the
+match more than one pattern. This allows you to use more complex
+file exclusion/inclusion behavior. However, it is recommended to use
 ``.pxarexclude`` files instead for such cases.
 
 For example you might want to exclude all ``.txt`` files except for a specific
 one from the archive. This is achieved via the negated match pattern, prefixed
 by ``!``.
-All the glob pattern are relative to the ``source`` directory.
+All the glob patterns are relative to the ``source`` directory.
 
 .. code-block:: console
 
-    # pxar create archive.pxar source '**/*.txt' '!/folder/file.txt'
+    # pxar create archive.pxar /path/to/source --exclude '**/*.txt' --exclude '!/folder/file.txt'
 
-.. NOTE:: The order of the glob match patterns matters as later ones win over
+.. NOTE:: The order of the glob match patterns matters as later ones override
     previous ones. Permutations of the same patterns lead to different results.
 
 ``pxar`` will store the list of glob match patterns passed as parameters via the
-command line in a file called ``.pxarexclude-cli`` and store it at the root of
+command line, in a file called ``.pxarexclude-cli`` at the root of
 the archive.
 If a file with this name is already present in the source folder during archive
 creation, this file is not included in the archive and the file containing the
@@ -79,38 +78,38 @@ It is possible to create and place these files in any directory of the filesyste
 tree.
 These files must contain one pattern per line, again later patterns win over
 previous ones.
-The patterns control file exclusion of files present within the given directory
+The patterns control file exclusions of files present within the given directory
 or further below it in the tree.
-The behaviour is the same as described in :ref:`creating-backups`.
+The behavior is the same as described in :ref:`creating-backups`.
 
 Extracting an Archive
 ^^^^^^^^^^^^^^^^^^^^^
 
-An existing archive ``archive.pxar`` is extracted to a ``target`` directory
+An existing archive, ``archive.pxar``, is extracted to a ``target`` directory
 with the following command:
 
 .. code-block:: console
 
-    # pxar extract archive.pxar --target target
+    # pxar extract archive.pxar /path/to/target
 
 If no target is provided, the content of the archive is extracted to the current
 working directory.
 
-In order to restore only part of an archive or single files and/or folders,
+In order to restore only parts of an archive, single files, and/or folders,
 it is possible to pass the corresponding glob match patterns as additional
-parameters or use the patterns stored in a file:
+parameters or to use the patterns stored in a file:
 
 .. code-block:: console
 
-    # pxar extract etc.pxar '**/*.conf' --target /restore/target/etc
+    # pxar extract etc.pxar /restore/target/etc --pattern '**/*.conf'
 
 The above example restores all ``.conf`` files encountered in any of the
 sub-folders in the archive ``etc.pxar`` to the target ``/restore/target/etc``.
 A path to the file containing match patterns can be specified using the
 ``--files-from`` parameter.
 
-List the Content of an Archive
+List the Contents of an Archive
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To display the files and directories contained in an archive ``archive.pxar``,
 run the following command:
@@ -126,7 +125,7 @@ Mounting an Archive
 ^^^^^^^^^^^^^^^^^^^
 
 ``pxar`` allows you to mount and inspect the contents of an archive via _`FUSE`.
-In order to mount an archive named ``archive.pxar`` to the mountpoint ``mnt``,
+In order to mount an archive named ``archive.pxar`` to the mountpoint ``/mnt``,
 run the command:
 
 .. code-block:: console

docs/storage.rst

@@ -0,0 +1,244 @@
+Storage
+=======
+
+Disk Management
+---------------
+
+.. image:: images/screenshots/pbs-gui-disks.png
+  :align: right
+  :alt: List of disks
+
+Proxmox Backup Server comes with a set of disk utilities, which are
+accessed using the ``disk`` subcommand. This subcommand allows you to initialize
+disks, create various filesystems, and get information about the disks.
+
+To view the disks connected to the system, navigate to **Administration ->
+Disks** in the web interface or use the ``list`` subcommand of
+``disk``:
+
+.. code-block:: console
+
+  # proxmox-backup-manager disk list
+  ┌──────┬────────┬─────┬───────────┬─────────────┬───────────────┬─────────┬────────┐
+  │ name │ used   │ gpt │ disk-type │        size │ model         │ wearout │ status │
+  ╞══════╪════════╪═════╪═══════════╪═════════════╪═══════════════╪═════════╪════════╡
+  │ sda  │ lvm    │   1 │ hdd       │ 34359738368 │ QEMU_HARDDISK │       - │ passed │
+  ├──────┼────────┼─────┼───────────┼─────────────┼───────────────┼─────────┼────────┤
+  │ sdb  │ unused │   1 │ hdd       │ 68719476736 │ QEMU_HARDDISK │       - │ passed │
+  ├──────┼────────┼─────┼───────────┼─────────────┼───────────────┼─────────┼────────┤
+  │ sdc  │ unused │   1 │ hdd       │ 68719476736 │ QEMU_HARDDISK │       - │ passed │
+  └──────┴────────┴─────┴───────────┴─────────────┴───────────────┴─────────┴────────┘
+
+To initialize a disk with a new GPT, use the ``initialize`` subcommand:
+
+.. code-block:: console
+
+  # proxmox-backup-manager disk initialize sdX
+
+.. image:: images/screenshots/pbs-gui-disks-dir-create.png
+  :align: right
+  :alt: Create a directory
+
+You can create an ``ext4`` or ``xfs`` filesystem on a disk using ``fs
+create``, or by navigating to **Administration -> Disks -> Directory** in the
+web interface and creating one from there. The following command creates an
+``ext4`` filesystem and passes the ``--add-datastore`` parameter, in order to
+automatically create a datastore on the disk (in this case ``sdd``). This will
+create a datastore at the location ``/mnt/datastore/store1``:
+
+.. code-block:: console
+
+  # proxmox-backup-manager disk fs create store1 --disk sdd --filesystem ext4 --add-datastore true
+
+.. image:: images/screenshots/pbs-gui-disks-zfs-create.png
+  :align: right
+  :alt: Create ZFS
+
+You can also create a ``zpool`` with various raid levels from **Administration
+-> Disks -> Zpool** in the web interface, or by using ``zpool create``. The command
+below creates a mirrored ``zpool`` using two disks (``sdb`` & ``sdc``) and
+mounts it on the root directory (default):
+
+.. code-block:: console
+
+  # proxmox-backup-manager disk zpool create zpool1 --devices sdb,sdc --raidlevel mirror
+
+.. note:: You can also pass the ``--add-datastore`` parameter here, to automatically
+  create a datastore from the disk.
+
+You can use ``disk fs list`` and ``disk zpool list`` to keep track of your
+filesystems and zpools respectively.
+
+Proxmox Backup Server uses the package smartmontools. This is a set of tools
+used to monitor and control the S.M.A.R.T. system for local hard disks. If a
+disk supports S.M.A.R.T. capability, and you have this enabled, you can
+display S.M.A.R.T. attributes from the web interface or by using the command:
+
+.. code-block:: console
+
+  # proxmox-backup-manager disk smart-attributes sdX
+
+.. note:: This functionality may also be accessed directly through the use of
+  the ``smartctl`` command, which comes as part of the smartmontools package
+  (see ``man smartctl`` for more details).
+
+
+.. _datastore_intro:
+
+:term:`DataStore`
+-----------------
+
+A datastore refers to a location at which 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 this
+when setting up the datastore. The configuration information for datastores
+is stored in the file ``/etc/proxmox-backup/datastore.cfg``.
+
+.. note:: The `File Layout`_ requires the file system to support at least *65538*
+   subdirectories per directory. That number comes from the 2\ :sup:`16`
+   pre-created chunk namespace directories, and the ``.`` and ``..`` default
+   directory entries. This requirement excludes certain filesystems and
+   filesystem configuration from being supported for a datastore. For example,
+   ``ext3`` as a whole or ``ext4`` with the ``dir_nlink`` feature manually disabled.
+
+
+Datastore Configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: images/screenshots/pbs-gui-datastore.png
+  :align: right
+  :alt: Datastore Overview
+
+You can configure multiple datastores. Minimum one datastore needs to be
+configured. The datastore is identified by a simple *name* and points to a
+directory on the filesystem. Each datastore also has associated retention
+settings of how many backup snapshots for each interval of ``hourly``,
+``daily``, ``weekly``, ``monthly``, ``yearly`` as well as a time-independent
+number of backups to keep in that store. :ref:`backup-pruning` and
+:ref:`garbage collection <garbage-collection>` can also be configured to run
+periodically based on a configured schedule (see :ref:`calendar-events`) per datastore.
+
+
+Creating a Datastore
+^^^^^^^^^^^^^^^^^^^^
+.. image:: images/screenshots/pbs-gui-datastore-create-general.png
+  :align: right
+  :alt: Create a datastore
+
+You can create a new datastore from the web GUI, by navigating to **Datastore** in
+the menu tree and clicking **Create**. Here:
+
+* *Name* refers to the name of the datastore
+* *Backing Path* is the path to the directory upon which you want to create the
+  datastore
+* *GC Schedule* refers to the time and intervals at which garbage collection
+  runs
+* *Prune Schedule* refers to the frequency at which pruning takes place
+* *Prune Options* set the amount of backups which you would like to keep (see :ref:`backup-pruning`).
+
+Alternatively you can create a new datastore from the command line. 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
+
+
+Managing Datastores
+^^^^^^^^^^^^^^^^^^^
+
+To list existing datastores from the command line run:
+
+.. code-block:: console
+
+  # proxmox-backup-manager datastore list
+  ┌────────┬──────────────────────┬─────────────────────────────┐
+  │ name   │ path                 │ comment                     │
+  ╞════════╪══════════════════════╪═════════════════════════════╡
+  │ store1 │ /backup/disk1/store1 │ This is my default storage. │
+  └────────┴──────────────────────┴─────────────────────────────┘
+
+You can change the garbage collection and prune settings of a datastore, by
+editing the datastore from the GUI or by using the ``update`` subcommand. For
+example, the below command changes the garbage collection schedule using the
+``update`` subcommand and prints the properties of the datastore with the
+``show`` subcommand:
+
+.. code-block:: console
+
+  # proxmox-backup-manager datastore update store1 --gc-schedule 'Tue 04:27'
+  # proxmox-backup-manager datastore show store1
+  ┌────────────────┬─────────────────────────────┐
+  │ Name           │ Value                       │
+  ╞════════════════╪═════════════════════════════╡
+  │ name           │ store1                      │
+  ├────────────────┼─────────────────────────────┤
+  │ path           │ /backup/disk1/store1        │
+  ├────────────────┼─────────────────────────────┤
+  │ comment        │ This is my default storage. │
+  ├────────────────┼─────────────────────────────┤
+  │ gc-schedule    │ Tue 04:27                   │
+  ├────────────────┼─────────────────────────────┤
+  │ keep-last      │ 7                           │
+  ├────────────────┼─────────────────────────────┤
+  │ prune-schedule │ daily                       │
+  └────────────────┴─────────────────────────────┘
+
+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
+^^^^^^^^^^^
+
+After creating a datastore, the following default layout will appear:
+
+.. code-block:: console
+
+  # ls -arilh /backup/disk1/store1
+  276493 -rw-r--r-- 1 backup backup       0 Jul  8 12:35 .lock
+  276490 drwxr-x--- 1 backup backup 1064960 Jul  8 12:35 .chunks
+
+`.lock` is an empty file used for process locking.
+
+The `.chunks` directory contains folders, starting from `0000` and taking hexadecimal values until `ffff`. These
+directories will store the chunked data after a backup operation has been executed.
+
+.. code-block:: console
+
+ # ls -arilh /backup/disk1/store1/.chunks
+ 545824 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 ffff
+ 545823 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 fffe
+ 415621 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 fffd
+ 415620 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 fffc
+ 353187 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 fffb
+ 344995 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 fffa
+ 144079 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 fff9
+ 144078 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 fff8
+ 144077 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 fff7
+ ...
+ 403180 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 000c
+ 403179 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 000b
+ 403177 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 000a
+ 402530 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0009
+ 402513 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0008
+ 402509 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0007
+ 276509 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0006
+ 276508 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0005
+ 276507 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0004
+ 276501 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0003
+ 276499 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0002
+ 276498 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0001
+ 276494 drwxr-x--- 2 backup backup 4.0K Jul  8 12:35 0000
+ 276489 drwxr-xr-x 3 backup backup 4.0K Jul  8 12:35 ..
+ 276490 drwxr-x--- 1 backup backup 1.1M Jul  8 12:35 .
+
+

docs/sysadmin.rst

@@ -1,5 +1,5 @@
 Host System Administration
---------------------------
+==========================
 
 `Proxmox Backup`_ is based on the famous Debian_ Linux
 distribution. That means that you have access to the whole world of
@@ -23,8 +23,4 @@ either explain things which are different on `Proxmox Backup`_, or
 tasks which are commonly used on `Proxmox Backup`_. For other topics,
 please refer to the standard Debian documentation.
 
-ZFS
+.. include:: local-zfs.rst
-~~~
-
-.. todo:: Add local ZFS admin guide (local.zfs.adoc)
-

docs/system-requirements.rst

@@ -0,0 +1,57 @@
+System Requirements
+-------------------
+
+We recommend using high quality server hardware when running Proxmox Backup in
+production. To further decrease the impact of a failed host, you can set up
+periodic, efficient, incremental :ref:`datastore synchronization <syncjobs>`
+from other Proxmox Backup Server instances.
+
+Minimum Server Requirements, for Evaluation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These minimum requirements are for evaluation purposes only and should not be
+used in production.
+
+* CPU: 64bit (*x86-64* or *AMD64*), 2+ Cores
+
+* Memory (RAM): 2 GB RAM
+
+* Hard drive: more than 8GB of space.
+
+* Network card (NIC)
+
+
+Recommended Server System Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* CPU: Modern AMD or Intel 64-bit based CPU, with at least 4 cores
+
+* Memory: minimum 4 GiB for the OS, filesystem cache and Proxmox Backup Server
+  daemons. Add at least another GiB per TiB storage space.
+
+* OS storage:
+
+  * 32 GiB, or more, free storage space
+  * Use a hardware RAID with battery protected write cache (*BBU*) or a
+    redundant ZFS setup (ZFS is not compatible with a hardware RAID
+    controller).
+
+* Backup storage:
+
+  * Use only SSDs, for best results
+  * If HDDs are used: Using a metadata cache is highly recommended, for example,
+    add a ZFS :ref:`special device mirror <local_zfs_special_device>`.
+
+* Redundant Multi-GBit/s network interface cards (NICs)
+
+
+Supported Web Browsers for Accessing the Web Interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To access the server's web-based user interface, we recommend using one of the
+following browsers:
+
+* Firefox, a release from the current year, or the latest Extended Support Release
+* Chrome, a release from the current year
+* Microsoft's currently supported version of Edge
+* Safari, a release from the current year

docs/terminology.rst

@@ -0,0 +1,118 @@
+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, it can be split into *fixed* or *variable*
+sized chunks.
+
+Fixed sized chunking requires minimal CPU power, 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 Proxmox Backup Server supports both strategies.
+
+
+Image Archives: ``<name>.img``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is used for virtual machine images and other large binary
+data. Content is split into fixed-sized chunks.
+
+
+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.
+
+
+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
+    consists of the virtual machine's configuration file and an image archive
+    for each disk.
+
+``ct``
+    This type is used for :term:`container`\ s. Consists of the container's
+    configuration and a single file archive for the filesystem 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
+---------
+
+A 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*).
+
+

docs/todos.rst

@@ -0,0 +1,6 @@
+Documentation Todo List
+=======================
+
+This is an auto-generated list of the todo references in the documentation.
+
+.. todolist::

docs/user-management.rst

@@ -0,0 +1,186 @@
+.. _user_mgmt:
+
+User Management
+===============
+
+
+User Configuration
+------------------
+
+.. image:: images/screenshots/pbs-gui-user-management.png
+  :align: right
+  :alt: User management
+
+Proxmox Backup Server supports 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 need 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. User configuration information is stored in the file
+``/etc/proxmox-backup/user.cfg``. 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          │
+  └─────────────┴────────┴────────┴───────────┴──────────┴────────────────┴────────────────────┘
+
+.. image:: images/screenshots/pbs-gui-user-management-add-user.png
+  :align: right
+  :alt: Add a new user
+
+The superuser has full administration rights on everything, so you
+normally want to add other users with less privileges. You can create a new
+user with the ``user create`` subcommand or through the web interface, under
+**Configuration -> User Management**. The ``create`` subcommand lets you specify
+many options like ``--email`` or ``--password``. You can update or change any
+user properties using the ``update`` subcommand later (**Edit** in the GUI):
+
+
+.. code-block:: console
+
+  # proxmox-backup-manager user create john@pbs --email john@example.com
+  # 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 user 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 any permissions. Please read the next
+section to learn how to set access permissions.
+
+If you want to disable a 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 user with:
+
+.. code-block:: console
+
+  # proxmox-backup-manager user remove john@pbs
+
+
+.. _user_acl:
+
+Access Control
+--------------
+
+By default new users do not have any permission. Instead you need to
+specify what is allowed and what is not. You can do this by assigning
+roles to users on specific objects like datastores or remotes. The
+following roles exist:
+
+**NoAccess**
+  Disable Access - nothing is allowed.
+
+**Admin**
+  Can do anything.
+
+**Audit**
+  Can view things, but is not allowed to change settings.
+
+**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.
+
+.. image:: images/screenshots/pbs-gui-permissions-add.png
+  :align: right
+  :alt: Add permissions for user
+
+Access permission information is stored in ``/etc/proxmox-backup/acl.cfg``. The
+file contains 5 fields, separated using a colon (':') as a delimiter. A typical
+entry takes the form:
+
+``acl:1:/datastore:john@pbs:DatastoreBackup``
+
+The data represented in each field is as follows:
+
+#. ``acl`` identifier
+#. A ``1`` or ``0``, representing whether propagation is enabled or disabled,
+   respectively
+#. The object on which the permission is set. This can be a specific object
+   (single datastore, remote, etc.) or a top level object, which with
+   propagation enabled, represents all children of the object also.
+#. The user for which the permission is set
+#. The role being set
+
+You can manage datastore permissions from **Configuration -> Permissions** in the
+web interface. Likewise, you can use the ``acl`` subcommand to manage and
+monitor user permissions from the command line. For example, the command below
+will add the user ``john@pbs`` as a **DatastoreAdmin** for the datastore
+``store1``, located at ``/backup/disk1/store1``:
+
+.. code-block:: console
+
+  # proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --userid john@pbs
+
+You can monitor the roles of each user using the following command:
+
+.. code-block:: console
+
+   # proxmox-backup-manager acl list
+   ┌──────────┬──────────────────┬───────────┬────────────────┐
+   │ ugid     │ path             │ propagate │ roleid         │
+   ╞══════════╪══════════════════╪═══════════╪════════════════╡
+   │ john@pbs │ /datastore/disk1 │         1 │ DatastoreAdmin │
+   └──────────┴──────────────────┴───────────┴────────────────┘
+
+A single user can be assigned multiple permission sets for different datastores.
+
+.. Note::
+  Naming convention is important here. For datastores on the host,
+  you must use the convention ``/datastore/{storename}``. For example, to set
+  permissions for a datastore mounted at ``/mnt/backup/disk4/store2``, you would use
+  ``/datastore/store2`` for the path. For remote stores, use the convention
+  ``/remote/{remote}/{storename}``, where ``{remote}`` signifies the name of the
+  remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
+  the remote.
+
+

etc/Makefile

@@ -7,7 +7,7 @@ DYNAMIC_UNITS := \
 	proxmox-backup.service \
 	proxmox-backup-proxy.service
 
-all: $(UNITS) $(DYNAMIC_UNITS)
+all: $(UNITS) $(DYNAMIC_UNITS) pbstest-beta.list
 
 clean:
 	rm -f $(DYNAMIC_UNITS)

etc/pbstest-beta.list

@@ -0,0 +1 @@
+deb http://download.proxmox.com/debian/pbs buster pbstest

etc/proxmox-backup-proxy.service.in

@@ -2,7 +2,7 @@
 Description=Proxmox Backup API Proxy Server
 Wants=network-online.target
 After=network.target
-Requires=proxmox-backup.service
+Wants=proxmox-backup.service
 After=proxmox-backup.service
 
 [Service]

examples/cipherbench.rs

@@ -1,4 +1,4 @@
-use failure::*;
+use anyhow::{Error};
 
 //  chacha20-poly1305
 

examples/completion.rs

@@ -1,4 +1,4 @@
-use failure::*;
+use anyhow::{Error};
 
 use proxmox::api::{*, cli::*};
 
@@ -49,7 +49,7 @@ fn hello_command(
 }
 
 #[api(input: { properties: {} })]
-/// Quit command. Exit the programm.
+/// Quit command. Exit the program.
 ///
 /// Returns: nothing
 fn quit_command() -> Result<(), Error> {
@@ -83,7 +83,8 @@ fn main() -> Result<(), Error> {
 
         let args = shellword_split(&line)?;
 
-        let _ = handle_command(helper.cmd_def(), "", args, None);
+        let rpcenv = CliEnvironment::new();
+        let _ = handle_command(helper.cmd_def(), "", args, rpcenv, None);
 
         rl.add_history_entry(line);
     }

examples/download-speed.rs

@@ -1,9 +1,8 @@
 use std::io::Write;
 
-use failure::*;
+use anyhow::{Error};
-
-use chrono::{DateTime, Utc};
 
+use proxmox_backup::api2::types::Userid;
 use proxmox_backup::client::{HttpClient, HttpClientOptions, BackupReader};
 
 pub struct DummyWriter {
@@ -27,15 +26,15 @@ async fn run() -> Result<(), Error> {
 
     let host = "localhost";
 
-    let username = "root@pam";
+    let username = Userid::root_userid();
 
     let options = HttpClientOptions::new()
         .interactive(true)
         .ticket_cache(true);
 
-    let client = HttpClient::new(host, username, options)?;
+    let client = HttpClient::new(host, 8007, username, options)?;
 
-    let backup_time = "2019-06-28T10:49:48Z".parse::<DateTime<Utc>>()?;
+    let backup_time = proxmox::tools::time::parse_rfc3339("2019-06-28T10:49:48Z")?;
 
     let client = BackupReader::start(client, None, "store2", "host", "elsa", backup_time, true)
         .await?;
@@ -44,8 +43,8 @@ async fn run() -> Result<(), Error> {
 
     let mut bytes = 0;
     for _ in 0..100 {
-        let writer = DummyWriter { bytes: 0 };
+        let mut writer = DummyWriter { bytes: 0 };
-        let writer = client.speedtest(writer).await?;
+        client.speedtest(&mut writer).await?;
         println!("Received {} bytes", writer.bytes);
         bytes += writer.bytes;
     }
@@ -59,8 +58,7 @@ async fn run() -> Result<(), Error> {
     Ok(())
 }
 
-#[tokio::main]
+fn main() {
-async fn main() {
     if let Err(err) = proxmox_backup::tools::runtime::main(run()) {
         eprintln!("ERROR: {}", err);
     }

examples/dynamic-files.rs

@@ -1,4 +1,4 @@
-use failure::*;
+use anyhow::{bail, Error};
 
 use std::thread;
 use std::path::PathBuf;
@@ -16,7 +16,7 @@ use std::io::Write;
 // tar: dyntest1/testfile7.dat: File shrank by 2833252864 bytes; padding with zeros
 
 // # pxar create test.pxar ./dyntest1/
-// Error: detected shrinked file "./dyntest1/testfile0.dat" (22020096 < 12679380992)
+// Error: detected shrunk file "./dyntest1/testfile0.dat" (22020096 < 12679380992)
 
 fn create_large_file(path: PathBuf) {
 

examples/h2client.rs

@@ -2,7 +2,7 @@ use std::future::Future;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-use failure::*;
+use anyhow::{Error};
 use futures::future::TryFutureExt;
 use futures::stream::Stream;
 use tokio::net::TcpStream;

examples/h2s-client.rs

@@ -2,7 +2,7 @@ use std::future::Future;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-use failure::*;
+use anyhow::{format_err, Error};
 use futures::future::TryFutureExt;
 use futures::stream::Stream;
 

examples/h2s-server.rs

@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use failure::*;
+use anyhow::{format_err, Error};
 use futures::*;
 use hyper::{Request, Response, Body};
 use openssl::ssl::{SslMethod, SslAcceptor, SslFiletype};

examples/h2server.rs

@@ -1,4 +1,4 @@
-use failure::*;
+use anyhow::{Error};
 use futures::*;
 
 // Simple H2 server to test H2 speed with h2client.rs

examples/test_chunk_size.rs

@@ -2,7 +2,7 @@ extern crate proxmox_backup;
 
 // also see https://www.johndcook.com/blog/standard_deviation/
 
-use failure::*;
+use anyhow::{Error};
 use std::io::{Read, Write};
 
 use proxmox_backup::backup::*;

examples/test_chunk_speed2.rs

@@ -1,4 +1,4 @@
-use failure::*;
+use anyhow::{Error};
 use futures::*;
 
 extern crate proxmox_backup;

examples/upload-speed.rs

@@ -1,26 +1,27 @@
-use failure::*;
+use anyhow::{Error};
 
+use proxmox_backup::api2::types::Userid;
 use proxmox_backup::client::*;
 
-async fn upload_speed() -> Result<usize, Error> {
+async fn upload_speed() -> Result<f64, Error> {
 
     let host = "localhost";
     let datastore = "store2";
 
-    let username = "root@pam";
+    let username = Userid::root_userid();
 
     let options = HttpClientOptions::new()
         .interactive(true)
         .ticket_cache(true);
 
-    let client = HttpClient::new(host, username, options)?;
+    let client = HttpClient::new(host, 8007, username, options)?;
 
-    let backup_time = chrono::Utc::now();
+    let backup_time = proxmox::tools::time::epoch_i64();
 
-    let client = BackupWriter::start(client, datastore, "host", "speedtest", backup_time, false).await?;
+    let client = BackupWriter::start(client, None, datastore, "host", "speedtest", backup_time, false, true).await?;
 
     println!("start upload speed test");
-    let res = client.upload_speedtest().await?;
+    let res = client.upload_speedtest(true).await?;
 
     Ok(res)
 }

src/api2.rs

@@ -1,13 +1,14 @@
-mod access;
+pub mod access;
 pub mod admin;
 pub mod backup;
 pub mod config;
 pub mod node;
 pub mod reader;
-mod subscription;
+pub mod status;
 pub mod types;
 pub mod version;
 pub mod pull;
+mod helpers;
 
 use proxmox::api::router::SubdirMap;
 use proxmox::api::Router;
@@ -23,7 +24,7 @@ pub const SUBDIRS: SubdirMap = &[
     ("nodes", &NODES_ROUTER),
     ("pull", &pull::ROUTER),
     ("reader", &reader::ROUTER),
-    ("subscription", &subscription::ROUTER),
+    ("status", &status::ROUTER),
     ("version", &version::ROUTER),
 ];
 

src/api2/access.rs

@@ -1,51 +1,110 @@
-use failure::*;
+use anyhow::{bail, format_err, Error};
 
 use serde_json::{json, Value};
 
-use proxmox::api::api;
+use proxmox::api::{api, RpcEnvironment, Permission};
 use proxmox::api::router::{Router, SubdirMap};
-use proxmox::sortable;
+use proxmox::{sortable, identity};
 use proxmox::{http_err, list_subdirs_api_method};
 
-use crate::tools;
+use crate::tools::ticket::{self, Empty, Ticket};
-use crate::tools::ticket::*;
 use crate::auth_helpers::*;
+use crate::api2::types::*;
 
-fn authenticate_user(username: &str, password: &str) -> Result<(), Error> {
+use crate::config::cached_user_info::CachedUserInfo;
+use crate::config::acl::{PRIVILEGES, PRIV_PERMISSIONS_MODIFY};
 
-    let ticket_lifetime = tools::ticket::TICKET_LIFETIME;
+pub mod user;
+pub mod domain;
+pub mod acl;
+pub mod role;
+
+/// returns Ok(true) if a ticket has to be created
+/// and Ok(false) if not
+fn authenticate_user(
+    userid: &Userid,
+    password: &str,
+    path: Option<String>,
+    privs: Option<String>,
+    port: Option<u16>,
+) -> Result<bool, Error> {
+    let user_info = CachedUserInfo::new()?;
+
+    if !user_info.is_active_user(&userid) {
+        bail!("user account disabled or expired.");
+    }
 
     if password.starts_with("PBS:") {
-        if let Ok((_age, Some(ticket_username))) = tools::ticket::verify_rsa_ticket(public_auth_key(), "PBS", password, None, -300, ticket_lifetime) {
+        if let Ok(ticket_userid) = Ticket::<Userid>::parse(password)
-            if ticket_username == username {
+            .and_then(|ticket| ticket.verify(public_auth_key(), "PBS", None))
-                return Ok(());
+        {
-            } else {
+            if *userid == ticket_userid {
-                bail!("ticket login failed - wrong username");
+                return Ok(true);
             }
+            bail!("ticket login failed - wrong userid");
+        }
+    } else if password.starts_with("PBSTERM:") {
+        if path.is_none() || privs.is_none() || port.is_none() {
+            bail!("cannot check termnal ticket without path, priv and port");
+        }
+
+        let path = path.ok_or_else(|| format_err!("missing path for termproxy ticket"))?;
+        let privilege_name = privs
+            .ok_or_else(|| format_err!("missing privilege name for termproxy ticket"))?;
+        let port = port.ok_or_else(|| format_err!("missing port for termproxy ticket"))?;
+
+        if let Ok(Empty) = Ticket::parse(password)
+            .and_then(|ticket| ticket.verify(
+                public_auth_key(),
+                ticket::TERM_PREFIX,
+                Some(&ticket::term_aad(userid, &path, port)),
+            ))
+        {
+            for (name, privilege) in PRIVILEGES {
+                if *name == privilege_name {
+                    let mut path_vec = Vec::new();
+                    for part in path.split('/') {
+                        if part != "" {
+                            path_vec.push(part);
+                        }
+                    }
+
+                    user_info.check_privs(userid, &path_vec, *privilege, false)?;
+                    return Ok(false);
+                }
+            }
+
+            bail!("No such privilege");
         }
     }
 
-    if username == "root@pam" {
+    let _ = crate::auth::authenticate_user(userid, password)?;
-        let mut auth = pam::Authenticator::with_password("proxmox-backup-auth").unwrap();
+    Ok(true)
-        auth.get_handler().set_credentials("root", password);
-        auth.authenticate()?;
-        return Ok(());
-    }
-
-    bail!("inavlid credentials");
 }
 
 #[api(
     input: {
         properties: {
             username: {
-                type: String,
+                type: Userid,
-                description: "User name.",
-                max_length: 64,
             },
             password: {
+                schema: PASSWORD_SCHEMA,
+            },
+            path: {
                 type: String,
-                description: "The secret password. This can also be a valid ticket.",
+                description: "Path for verifying terminal tickets.",
+                optional: true,
+            },
+            privs: {
+                type: String,
+                description: "Privilege for verifying terminal tickets.",
+                optional: true,
+            },
+            port: {
+                type: Integer,
+                description: "Port for verifying terminal tickets.",
+                optional: true,
             },
         },
     },
@@ -66,15 +125,23 @@ fn authenticate_user(username: &str, password: &str) -> Result<(), Error> {
         },
     },
     protected: true,
+    access: {
+        permission: &Permission::World,
+    },
 )]
 /// Create or verify authentication ticket.
 ///
 /// Returns: An authentication ticket with additional infos.
-fn create_ticket(username: String, password: String) -> Result<Value, Error> {
+fn create_ticket(
-    match authenticate_user(&username, &password) {
+    username: Userid,
-        Ok(_) => {
+    password: String,
-
+    path: Option<String>,
-            let ticket = assemble_rsa_ticket( private_auth_key(), "PBS", Some(&username), None)?;
+    privs: Option<String>,
+    port: Option<u16>,
+) -> Result<Value, Error> {
+    match authenticate_user(&username, &password, path, privs, port) {
+        Ok(true) => {
+            let ticket = Ticket::new("PBS", &username)?.sign(private_auth_key(), None)?;
 
             let token = assemble_csrf_prevention_token(csrf_secret(), &username);
 
@@ -86,21 +153,84 @@ fn create_ticket(username: String, password: String) -> Result<Value, Error> {
                 "CSRFPreventionToken": token,
             }))
         }
+        Ok(false) => Ok(json!({
+            "username": username,
+        })),
         Err(err) => {
             let client_ip = "unknown"; // $rpcenv->get_client_ip() || '';
             log::error!("authentication failure; rhost={} user={} msg={}", client_ip, username, err.to_string());
-            Err(http_err!(UNAUTHORIZED, "permission check failed.".into()))
+            Err(http_err!(UNAUTHORIZED, "permission check failed."))
         }
     }
 }
 
+#[api(
+    input: {
+        properties: {
+            userid: {
+                type: Userid,
+            },
+            password: {
+                schema: PASSWORD_SCHEMA,
+            },
+        },
+    },
+    access: {
+        description: "Anybody is allowed to change there own password. In addition, users with 'Permissions:Modify' privilege may change any password.",
+        permission: &Permission::Anybody,
+    },
+
+)]
+/// Change user password
+///
+/// Each user is allowed to change his own password. Superuser
+/// can change all passwords.
+fn change_password(
+    userid: Userid,
+    password: String,
+    rpcenv: &mut dyn RpcEnvironment,
+) -> Result<Value, Error> {
+
+    let current_user: Userid = rpcenv
+        .get_user()
+        .ok_or_else(|| format_err!("unknown user"))?
+        .parse()?;
+
+    let mut allowed = userid == current_user;
+
+    if userid == "root@pam" { allowed = true; }
+
+    if !allowed {
+        let user_info = CachedUserInfo::new()?;
+        let privs = user_info.lookup_privs(&current_user, &[]);
+        if (privs & PRIV_PERMISSIONS_MODIFY) != 0 { allowed = true; }
+    }
+
+    if !allowed {
+        bail!("you are not authorized to change the password.");
+    }
+
+    let authenticator = crate::auth::lookup_authenticator(userid.realm())?;
+    authenticator.store_password(userid.name(), &password)?;
+
+    Ok(Value::Null)
+}
+
 #[sortable]
-const SUBDIRS: SubdirMap = &[
+const SUBDIRS: SubdirMap = &sorted!([
+    ("acl", &acl::ROUTER),
+    (
+        "password", &Router::new()
+            .put(&API_METHOD_CHANGE_PASSWORD)
+    ),
     (
         "ticket", &Router::new()
             .post(&API_METHOD_CREATE_TICKET)
-    )
+    ),
-];
+    ("domains", &domain::ROUTER),
+    ("roles", &role::ROUTER),
+    ("users", &user::ROUTER),
+]);
 
 pub const ROUTER: Router = Router::new()
     .get(&list_subdirs_api_method!(SUBDIRS))

src/api2/access/acl.rs

@@ -0,0 +1,229 @@
+use anyhow::{bail, Error};
+use ::serde::{Deserialize, Serialize};
+
+use proxmox::api::{api, Router, RpcEnvironment, Permission};
+use proxmox::tools::fs::open_file_locked;
+
+use crate::api2::types::*;
+use crate::config::acl;
+use crate::config::acl::{Role, PRIV_SYS_AUDIT, PRIV_PERMISSIONS_MODIFY};
+
+#[api(
+    properties: {
+        propagate: {
+            schema: ACL_PROPAGATE_SCHEMA,
+        },
+ 	path: {
+            schema: ACL_PATH_SCHEMA,
+        },
+        ugid_type: {
+            schema: ACL_UGID_TYPE_SCHEMA,
+        },
+	ugid: {
+            type: String,
+            description: "User or Group ID.",
+        },
+	roleid: {
+            type: Role,
+        }
+    }
+)]
+#[derive(Serialize, Deserialize)]
+/// ACL list entry.
+pub struct AclListItem {
+    path: String,
+    ugid: String,
+    ugid_type: String,
+    propagate: bool,
+    roleid: String,
+}
+
+fn extract_acl_node_data(
+    node: &acl::AclTreeNode,
+    path: &str,
+    list: &mut Vec<AclListItem>,
+    exact: bool,
+) {
+    for (user, roles) in &node.users {
+        for (role, propagate) in roles {
+            list.push(AclListItem {
+                path: if path.is_empty() { String::from("/") } else { path.to_string() },
+                propagate: *propagate,
+                ugid_type: String::from("user"),
+                ugid: user.to_string(),
+                roleid: role.to_string(),
+            });
+        }
+    }
+    for (group, roles) in &node.groups {
+        for (role, propagate) in roles {
+            list.push(AclListItem {
+                path: if path.is_empty() { String::from("/") } else { path.to_string() },
+                propagate: *propagate,
+                ugid_type: String::from("group"),
+                ugid: group.to_string(),
+                roleid: role.to_string(),
+            });
+        }
+    }
+    if exact {
+        return;
+    }
+    for (comp, child) in &node.children {
+        let new_path = format!("{}/{}", path, comp);
+        extract_acl_node_data(child, &new_path, list, exact);
+    }
+}
+
+#[api(
+    input: {
+        properties: {
+	    path: {
+                schema: ACL_PATH_SCHEMA,
+                optional: true,
+            },
+            exact: {
+                description: "If set, returns only ACL for the exact path.",
+                type: bool,
+                optional: true,
+                default: false,
+            },
+        },
+    },
+    returns: {
+        description: "ACL entry list.",
+        type: Array,
+        items: {
+            type: AclListItem,
+        }
+    },
+    access: {
+        permission: &Permission::Privilege(&["access", "acl"], PRIV_SYS_AUDIT, false),
+    },
+)]
+/// Read Access Control List (ACLs).
+pub fn read_acl(
+    path: Option<String>,
+    exact: bool,
+    mut rpcenv: &mut dyn RpcEnvironment,
+) -> Result<Vec<AclListItem>, Error> {
+
+    //let auth_user = rpcenv.get_user().unwrap();
+
+    let (mut tree, digest) = acl::config()?;
+
+    let mut list: Vec<AclListItem> = Vec::new();
+    if let Some(path) = &path {
+        if let Some(node) = &tree.find_node(path) {
+            extract_acl_node_data(&node, path, &mut list, exact);
+        }
+    } else {
+        extract_acl_node_data(&tree.root, "", &mut list, exact);
+    }
+
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
+
+    Ok(list)
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+	    path: {
+                schema: ACL_PATH_SCHEMA,
+            },
+	    role: {
+                type: Role,
+            },
+            propagate: {
+                optional: true,
+                schema: ACL_PROPAGATE_SCHEMA,
+            },
+            userid: {
+                optional: true,
+                type: Userid,
+            },
+            group: {
+                optional: true,
+                schema: PROXMOX_GROUP_ID_SCHEMA,
+            },
+            delete: {
+                optional: true,
+                description: "Remove permissions (instead of adding it).",
+                type: bool,
+            },
+            digest: {
+                optional: true,
+                schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
+            },
+       },
+    },
+    access: {
+        permission: &Permission::Privilege(&["access", "acl"], PRIV_PERMISSIONS_MODIFY, false),
+    },
+)]
+/// Update Access Control List (ACLs).
+pub fn update_acl(
+    path: String,
+    role: String,
+    propagate: Option<bool>,
+    userid: Option<Userid>,
+    group: Option<String>,
+    delete: Option<bool>,
+    digest: Option<String>,
+    _rpcenv: &mut dyn RpcEnvironment,
+) -> Result<(), Error> {
+
+    let _lock = open_file_locked(acl::ACL_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
+
+    let (mut tree, expected_digest) = acl::config()?;
+
+    if let Some(ref digest) = digest {
+        let digest = proxmox::tools::hex_to_digest(digest)?;
+        crate::tools::detect_modified_configuration_file(&digest, &expected_digest)?;
+    }
+
+    let propagate = propagate.unwrap_or(true);
+
+    let delete = delete.unwrap_or(false);
+
+    if let Some(ref _group) = group {
+        bail!("parameter 'group' - groups are currently not supported.");
+    } else if let Some(ref userid) = userid {
+        if !delete { // Note: we allow to delete non-existent users
+            let user_cfg = crate::config::user::cached_config()?;
+            if user_cfg.sections.get(&userid.to_string()).is_none() {
+                bail!("no such user.");
+            }
+        }
+    } else {
+        bail!("missing 'userid' or 'group' parameter.");
+    }
+
+    if !delete { // Note: we allow to delete entries with invalid path
+        acl::check_acl_path(&path)?;
+    }
+
+    if let Some(userid) = userid {
+        if delete {
+            tree.delete_user_role(&path, &userid, &role);
+        } else {
+            tree.insert_user_role(&path, &userid, &role, propagate);
+        }
+    } else if let Some(group) = group {
+        if delete {
+            tree.delete_group_role(&path, &group, &role);
+        } else {
+            tree.insert_group_role(&path, &group, &role, propagate);
+        }
+    }
+
+    acl::save_config(&tree)?;
+
+    Ok(())
+}
+
+pub const ROUTER: Router = Router::new()
+    .get(&API_METHOD_READ_ACL)
+    .put(&API_METHOD_UPDATE_ACL);

src/api2/access/domain.rs

@@ -0,0 +1,47 @@
+use anyhow::{Error};
+
+use serde_json::{json, Value};
+
+use proxmox::api::{api, Permission};
+use proxmox::api::router::Router;
+
+use crate::api2::types::*;
+
+#[api(
+    returns: {
+        description: "List of realms.",
+        type: Array,
+        items: {
+            type: Object,
+            description: "User configuration (without password).",
+            properties: {
+                realm: {
+                    description: "Realm ID.",
+                    type: String,
+                },
+                comment: {
+                    schema: SINGLE_LINE_COMMENT_SCHEMA,
+                    optional: true,
+                },
+                default: {
+                    description: "Default realm.",
+                    type: bool,
+                }
+            },
+        }
+    },
+    access: {
+        description: "Anyone can access this, because we need that list for the login box (before the user is authenticated).",
+        permission: &Permission::World,
+    }
+)]
+/// Authentication domain/realm index.
+fn list_domains() -> Result<Value, Error> {
+    let mut list = Vec::new();
+    list.push(json!({ "realm": "pam", "comment": "Linux PAM standard authentication", "default": true }));
+    list.push(json!({ "realm": "pbs", "comment": "Proxmox Backup authentication server" }));
+    Ok(list.into())
+}
+
+pub const ROUTER: Router = Router::new()
+    .get(&API_METHOD_LIST_DOMAINS);

src/api2/access/role.rs

@@ -0,0 +1,58 @@
+use anyhow::Error;
+
+use serde_json::{json, Value};
+
+use proxmox::api::{api, Permission};
+use proxmox::api::router::Router;
+
+use crate::api2::types::*;
+use crate::config::acl::{Role, ROLE_NAMES, PRIVILEGES};
+
+#[api(
+    returns: {
+        description: "List of roles.",
+        type: Array,
+        items: {
+            type: Object,
+            description: "Role with description and privileges.",
+            properties: {
+                roleid: {
+                    type: Role,
+                },
+                privs: {
+                    type: Array,
+                    description: "List of Privileges",
+                    items: {
+                        type: String,
+                        description: "A Privilege",
+                    },
+                },
+                comment: {
+                    schema: SINGLE_LINE_COMMENT_SCHEMA,
+                    optional: true,
+                },
+            },
+        }
+    },
+    access: {
+        permission: &Permission::Anybody,
+    }
+)]
+/// Role list
+fn list_roles() -> Result<Value, Error> {
+    let mut list = Vec::new();
+
+    for (role, (privs, comment)) in ROLE_NAMES.iter() {
+        let mut priv_list = Vec::new();
+        for (name, privilege) in PRIVILEGES.iter() {
+            if privs & privilege > 0 {
+                priv_list.push(name.clone());
+            }
+        }
+        list.push(json!({ "roleid": role, "privs": priv_list, "comment": comment }));
+    }
+    Ok(list.into())
+}
+
+pub const ROUTER: Router = Router::new()
+    .get(&API_METHOD_LIST_ROLES);

src/api2/access/user.rs

@@ -0,0 +1,315 @@
+use anyhow::{bail, Error};
+use serde_json::Value;
+
+use proxmox::api::{api, ApiMethod, Router, RpcEnvironment, Permission};
+use proxmox::api::schema::{Schema, StringSchema};
+use proxmox::tools::fs::open_file_locked;
+
+use crate::api2::types::*;
+use crate::config::user;
+use crate::config::acl::{PRIV_SYS_AUDIT, PRIV_PERMISSIONS_MODIFY};
+use crate::config::cached_user_info::CachedUserInfo;
+
+pub const PBS_PASSWORD_SCHEMA: Schema = StringSchema::new("User Password.")
+    .format(&PASSWORD_FORMAT)
+    .min_length(5)
+    .max_length(64)
+    .schema();
+
+#[api(
+    input: {
+        properties: {},
+    },
+    returns: {
+        description: "List users (with config digest).",
+        type: Array,
+        items: { type: user::User },
+    },
+    access: {
+        permission: &Permission::Anybody,
+        description: "Returns all or just the logged-in user, depending on privileges.",
+    },
+)]
+/// List users
+pub fn list_users(
+    _param: Value,
+    _info: &ApiMethod,
+    mut rpcenv: &mut dyn RpcEnvironment,
+) -> Result<Vec<user::User>, Error> {
+
+    let (config, digest) = user::config()?;
+
+    let userid: Userid = rpcenv.get_user().unwrap().parse()?;
+    let user_info = CachedUserInfo::new()?;
+
+    let top_level_privs = user_info.lookup_privs(&userid, &["access", "users"]);
+    let top_level_allowed = (top_level_privs & PRIV_SYS_AUDIT) != 0;
+
+    let filter_by_privs = |user: &user::User| {
+        top_level_allowed || user.userid == userid
+    };
+
+    let list:Vec<user::User> = config.convert_to_typed_array("user")?;
+
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
+
+    Ok(list.into_iter().filter(filter_by_privs).collect())
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            userid: {
+                type: Userid,
+            },
+            comment: {
+                schema: SINGLE_LINE_COMMENT_SCHEMA,
+                optional: true,
+            },
+            password: {
+                schema: PBS_PASSWORD_SCHEMA,
+                optional: true,
+            },
+            enable: {
+                schema: user::ENABLE_USER_SCHEMA,
+                optional: true,
+            },
+            expire: {
+                schema: user::EXPIRE_USER_SCHEMA,
+                optional: true,
+            },
+            firstname: {
+                schema: user::FIRST_NAME_SCHEMA,
+                optional: true,
+            },
+            lastname: {
+                schema: user::LAST_NAME_SCHEMA,
+                optional: true,
+            },
+            email: {
+                schema: user::EMAIL_SCHEMA,
+                optional: true,
+            },
+        },
+    },
+    access: {
+        permission: &Permission::Privilege(&["access", "users"], PRIV_PERMISSIONS_MODIFY, false),
+    },
+)]
+/// Create new user.
+pub fn create_user(password: Option<String>, param: Value) -> Result<(), Error> {
+
+    let _lock = open_file_locked(user::USER_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
+
+    let user: user::User = serde_json::from_value(param)?;
+
+    let (mut config, _digest) = user::config()?;
+
+    if let Some(_) = config.sections.get(user.userid.as_str()) {
+        bail!("user '{}' already exists.", user.userid);
+    }
+
+    let authenticator = crate::auth::lookup_authenticator(&user.userid.realm())?;
+
+    config.set_data(user.userid.as_str(), "user", &user)?;
+
+    user::save_config(&config)?;
+
+    if let Some(password) = password {
+        authenticator.store_password(user.userid.name(), &password)?;
+    }
+
+    Ok(())
+}
+
+#[api(
+   input: {
+        properties: {
+            userid: {
+                type: Userid,
+            },
+         },
+    },
+    returns: {
+        description: "The user configuration (with config digest).",
+        type: user::User,
+    },
+    access: {
+        permission: &Permission::Or(&[
+            &Permission::Privilege(&["access", "users"], PRIV_SYS_AUDIT, false),
+            &Permission::UserParam("userid"),
+        ]),
+    },
+)]
+/// Read user configuration data.
+pub fn read_user(userid: Userid, mut rpcenv: &mut dyn RpcEnvironment) -> Result<user::User, Error> {
+    let (config, digest) = user::config()?;
+    let user = config.lookup("user", userid.as_str())?;
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
+    Ok(user)
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            userid: {
+                type: Userid,
+            },
+            comment: {
+                optional: true,
+                schema: SINGLE_LINE_COMMENT_SCHEMA,
+            },
+            password: {
+                schema: PBS_PASSWORD_SCHEMA,
+                optional: true,
+            },
+            enable: {
+                schema: user::ENABLE_USER_SCHEMA,
+                optional: true,
+            },
+            expire: {
+                schema: user::EXPIRE_USER_SCHEMA,
+                optional: true,
+            },
+            firstname: {
+                schema: user::FIRST_NAME_SCHEMA,
+                optional: true,
+            },
+            lastname: {
+                schema: user::LAST_NAME_SCHEMA,
+                optional: true,
+            },
+            email: {
+                schema: user::EMAIL_SCHEMA,
+                optional: true,
+            },
+            digest: {
+                optional: true,
+                schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
+            },
+        },
+    },
+    access: {
+        permission: &Permission::Or(&[
+            &Permission::Privilege(&["access", "users"], PRIV_PERMISSIONS_MODIFY, false),
+            &Permission::UserParam("userid"),
+        ]),
+    },
+)]
+/// Update user configuration.
+pub fn update_user(
+    userid: Userid,
+    comment: Option<String>,
+    enable: Option<bool>,
+    expire: Option<i64>,
+    password: Option<String>,
+    firstname: Option<String>,
+    lastname: Option<String>,
+    email: Option<String>,
+    digest: Option<String>,
+) -> Result<(), Error> {
+
+    let _lock = open_file_locked(user::USER_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
+
+    let (mut config, expected_digest) = user::config()?;
+
+    if let Some(ref digest) = digest {
+        let digest = proxmox::tools::hex_to_digest(digest)?;
+        crate::tools::detect_modified_configuration_file(&digest, &expected_digest)?;
+    }
+
+    let mut data: user::User = config.lookup("user", userid.as_str())?;
+
+    if let Some(comment) = comment {
+        let comment = comment.trim().to_string();
+        if comment.is_empty() {
+            data.comment = None;
+        } else {
+            data.comment = Some(comment);
+        }
+    }
+
+    if let Some(enable) = enable {
+        data.enable = if enable { None } else { Some(false) };
+    }
+
+    if let Some(expire) = expire {
+        data.expire = if expire > 0 { Some(expire) } else { None };
+    }
+
+    if let Some(password) = password {
+        let authenticator = crate::auth::lookup_authenticator(userid.realm())?;
+        authenticator.store_password(userid.name(), &password)?;
+    }
+
+    if let Some(firstname) = firstname {
+        data.firstname = if firstname.is_empty() { None } else { Some(firstname) };
+    }
+
+    if let Some(lastname) = lastname {
+        data.lastname = if lastname.is_empty() { None } else { Some(lastname) };
+    }
+    if let Some(email) = email {
+        data.email = if email.is_empty() { None } else { Some(email) };
+    }
+
+    config.set_data(userid.as_str(), "user", &data)?;
+
+    user::save_config(&config)?;
+
+    Ok(())
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            userid: {
+                type: Userid,
+            },
+            digest: {
+                optional: true,
+                schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
+            },
+        },
+    },
+    access: {
+        permission: &Permission::Or(&[
+            &Permission::Privilege(&["access", "users"], PRIV_PERMISSIONS_MODIFY, false),
+            &Permission::UserParam("userid"),
+        ]),
+    },
+)]
+/// Remove a user from the configuration file.
+pub fn delete_user(userid: Userid, digest: Option<String>) -> Result<(), Error> {
+
+    let _lock = open_file_locked(user::USER_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
+
+    let (mut config, expected_digest) = user::config()?;
+
+    if let Some(ref digest) = digest {
+        let digest = proxmox::tools::hex_to_digest(digest)?;
+        crate::tools::detect_modified_configuration_file(&digest, &expected_digest)?;
+    }
+
+    match config.sections.get(userid.as_str()) {
+        Some(_) => { config.sections.remove(userid.as_str()); },
+        None => bail!("user '{}' does not exist.", userid),
+    }
+
+    user::save_config(&config)?;
+
+    Ok(())
+}
+
+const ITEM_ROUTER: Router = Router::new()
+    .get(&API_METHOD_READ_USER)
+    .put(&API_METHOD_UPDATE_USER)
+    .delete(&API_METHOD_DELETE_USER);
+
+pub const ROUTER: Router = Router::new()
+    .get(&API_METHOD_LIST_USERS)
+    .post(&API_METHOD_CREATE_USER)
+    .match_all("userid", &ITEM_ROUTER);

src/api2/admin.rs

@@ -2,9 +2,11 @@ use proxmox::api::router::{Router, SubdirMap};
 use proxmox::list_subdirs_api_method;
 
 pub mod datastore;
+pub mod sync;
 
 const SUBDIRS: SubdirMap = &[
-    ("datastore", &datastore::ROUTER)
+    ("datastore", &datastore::ROUTER),
+    ("sync", &sync::ROUTER)
 ];
 
 pub const ROUTER: Router = Router::new()

src/api2/admin/sync.rs

@@ -0,0 +1,114 @@
+use anyhow::{format_err, Error};
+use serde_json::Value;
+
+use proxmox::api::{api, ApiMethod, Router, RpcEnvironment};
+use proxmox::api::router::SubdirMap;
+use proxmox::{list_subdirs_api_method, sortable};
+
+use crate::api2::types::*;
+use crate::api2::pull::do_sync_job;
+use crate::config::sync::{self, SyncJobStatus, SyncJobConfig};
+use crate::server::UPID;
+use crate::config::jobstate::{Job, JobState};
+use crate::tools::systemd::time::{
+    parse_calendar_event, compute_next_event};
+
+#[api(
+    input: {
+        properties: {},
+    },
+    returns: {
+        description: "List configured jobs and their status.",
+        type: Array,
+        items: { type: sync::SyncJobStatus },
+    },
+)]
+/// List all sync jobs
+pub fn list_sync_jobs(
+    _param: Value,
+    mut rpcenv: &mut dyn RpcEnvironment,
+) -> Result<Vec<SyncJobStatus>, Error> {
+
+    let (config, digest) = sync::config()?;
+
+    let mut list: Vec<SyncJobStatus> = config.convert_to_typed_array("sync")?;
+
+    for job in &mut list {
+        let last_state = JobState::load("syncjob", &job.id)
+            .map_err(|err| format_err!("could not open statefile for {}: {}", &job.id, err))?;
+        let (upid, endtime, state, starttime) = match last_state {
+            JobState::Created { time } => (None, None, None, time),
+            JobState::Started { upid } => {
+                let parsed_upid: UPID = upid.parse()?;
+                (Some(upid), None, None, parsed_upid.starttime)
+            },
+            JobState::Finished { upid, state } => {
+                let parsed_upid: UPID = upid.parse()?;
+                (Some(upid), Some(state.endtime()), Some(state.to_string()), parsed_upid.starttime)
+            },
+        };
+
+        job.last_run_upid = upid;
+        job.last_run_state = state;
+        job.last_run_endtime = endtime;
+
+        let last = job.last_run_endtime.unwrap_or_else(|| starttime);
+
+        job.next_run = (|| -> Option<i64> {
+            let schedule = job.schedule.as_ref()?;
+            let event = parse_calendar_event(&schedule).ok()?;
+            // ignore errors
+            compute_next_event(&event, last, false).unwrap_or_else(|_| None)
+        })();
+    }
+
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
+
+    Ok(list)
+}
+
+#[api(
+    input: {
+        properties: {
+            id: {
+                schema: JOB_ID_SCHEMA,
+            }
+        }
+    }
+)]
+/// Runs the sync jobs manually.
+fn run_sync_job(
+    id: String,
+    _info: &ApiMethod,
+    rpcenv: &mut dyn RpcEnvironment,
+) -> Result<String, Error> {
+
+    let (config, _digest) = sync::config()?;
+    let sync_job: SyncJobConfig = config.lookup("sync", &id)?;
+
+    let userid: Userid = rpcenv.get_user().unwrap().parse()?;
+
+    let job = Job::new("syncjob", &id)?;
+
+    let upid_str = do_sync_job(job, sync_job, &userid, None)?;
+
+    Ok(upid_str)
+}
+
+#[sortable]
+const SYNC_INFO_SUBDIRS: SubdirMap = &[
+    (
+        "run",
+        &Router::new()
+            .post(&API_METHOD_RUN_SYNC_JOB)
+    ),
+];
+
+const SYNC_INFO_ROUTER: Router = Router::new()
+    .get(&list_subdirs_api_method!(SYNC_INFO_SUBDIRS))
+    .subdirs(SYNC_INFO_SUBDIRS);
+
+
+pub const ROUTER: Router = Router::new()
+    .get(&API_METHOD_LIST_SYNC_JOBS)
+    .match_all("id", &SYNC_INFO_ROUTER);

src/api2/backup.rs

@@ -1,4 +1,4 @@
-use failure::*;
+use anyhow::{bail, format_err, Error};
 use futures::*;
 use hyper::header::{HeaderValue, UPGRADE};
 use hyper::http::request::Parts;
@@ -6,14 +6,17 @@ use hyper::{Body, Response, StatusCode};
 use serde_json::{json, Value};
 
 use proxmox::{sortable, identity, list_subdirs_api_method};
-use proxmox::api::{ApiResponseFuture, ApiHandler, ApiMethod, Router, RpcEnvironment};
+use proxmox::api::{ApiResponseFuture, ApiHandler, ApiMethod, Router, RpcEnvironment, Permission};
 use proxmox::api::router::SubdirMap;
 use proxmox::api::schema::*;
 
-use crate::tools::{self, WrappedReaderStream};
+use crate::tools;
 use crate::server::{WorkerTask, H2Service};
 use crate::backup::*;
 use crate::api2::types::*;
+use crate::config::acl::PRIV_DATASTORE_BACKUP;
+use crate::config::cached_user_info::CachedUserInfo;
+use crate::tools::fs::lock_dir_noblock;
 
 mod environment;
 use environment::*;
@@ -35,8 +38,13 @@ pub const API_METHOD_UPGRADE_BACKUP: ApiMethod = ApiMethod::new(
             ("backup-id", false, &BACKUP_ID_SCHEMA),
             ("backup-time", false, &BACKUP_TIME_SCHEMA),
             ("debug", true, &BooleanSchema::new("Enable verbose debug logging.").schema()),
+            ("benchmark", true, &BooleanSchema::new("Job is a benchmark (do not keep data).").schema()),
         ]),
     )
+).access(
+    // Note: parameter 'store' is no uri parameter, so we need to test inside function body
+    Some("The user needs Datastore.Backup privilege on /datastore/{store} and needs to own the backup group."),
+    &Permission::Anybody
 );
 
 fn upgrade_to_backup_protocol(
@@ -47,10 +55,17 @@ fn upgrade_to_backup_protocol(
     rpcenv: Box<dyn RpcEnvironment>,
 ) -> ApiResponseFuture {
 
-    async move {
+async move {
     let debug = param["debug"].as_bool().unwrap_or(false);
+    let benchmark = param["benchmark"].as_bool().unwrap_or(false);
+
+    let userid: Userid = rpcenv.get_user().unwrap().parse()?;
 
     let store = tools::required_string_param(&param, "store")?.to_owned();
+
+    let user_info = CachedUserInfo::new()?;
+    user_info.check_privs(&userid, &["datastore", &store], PRIV_DATASTORE_BACKUP, false)?;
+
     let datastore = DataStore::lookup_datastore(&store)?;
 
     let backup_type = tools::required_string_param(&param, "backup-type")?;
@@ -73,46 +88,91 @@ fn upgrade_to_backup_protocol(
 
     let worker_id = format!("{}_{}_{}", store, backup_type, backup_id);
 
-    let username = rpcenv.get_user().unwrap();
     let env_type = rpcenv.env_type();
 
     let backup_group = BackupGroup::new(backup_type, backup_id);
-    let last_backup = BackupInfo::last_backup(&datastore.base_path(), &backup_group).unwrap_or(None);
-    let backup_dir = BackupDir::new_with_group(backup_group, backup_time);
 
-    if let Some(last) = &last_backup {
+    let worker_type = if backup_type == "host" && backup_id == "benchmark" {
+        if !benchmark {
+            bail!("unable to run benchmark without --benchmark flags");
+        }
+        "benchmark"
+    } else {
+        if benchmark {
+            bail!("benchmark flags is only allowed on 'host/benchmark'");
+        }
+        "backup"
+    };
+
+    // lock backup group to only allow one backup per group at a time
+    let (owner, _group_guard) = datastore.create_locked_backup_group(&backup_group, &userid)?;
+
+    // permission check
+    if owner != userid && worker_type != "benchmark" {
+        // only the owner is allowed to create additional snapshots
+        bail!("backup owner check failed ({} != {})", userid, owner);
+    }
+
+    let last_backup = {
+        let info = BackupInfo::last_backup(&datastore.base_path(), &backup_group, true).unwrap_or(None);
+        if let Some(info) = info {
+            let (manifest, _) = datastore.load_manifest(&info.backup_dir)?;
+            let verify = manifest.unprotected["verify_state"].clone();
+            match serde_json::from_value::<SnapshotVerifyState>(verify) {
+                Ok(verify) => {
+                    match verify.state {
+                        VerifyState::Ok => Some(info),
+                        VerifyState::Failed => None,
+                    }
+                },
+                Err(_) => {
+                    // no verify state found, treat as valid
+                    Some(info)
+                }
+            }
+        } else {
+            None
+        }
+    };
+
+    let backup_dir = BackupDir::with_group(backup_group.clone(), backup_time)?;
+
+    let _last_guard = if let Some(last) = &last_backup {
         if backup_dir.backup_time() <= last.backup_dir.backup_time() {
             bail!("backup timestamp is older than last backup.");
         }
-        // fixme: abort if last backup is still running - howto test?
-        // Idea: write upid into a file inside snapshot dir. then test if
-        // it is still running here.
-    }
 
-    let (path, is_new) = datastore.create_backup_dir(&backup_dir)?;
+        // lock last snapshot to prevent forgetting/pruning it during backup
-    if !is_new { bail!("backup directorty already exists."); }
+        let full_path = datastore.snapshot_path(&last.backup_dir);
+        Some(lock_dir_noblock(&full_path, "snapshot", "base snapshot is already locked by another operation")?)
+    } else {
+        None
+    };
 
-    WorkerTask::spawn("backup", Some(worker_id), &username.clone(), true, move |worker| {
+    let (path, is_new, _snap_guard) = datastore.create_locked_backup_dir(&backup_dir)?;
+    if !is_new { bail!("backup directory already exists."); }
+
+
+    WorkerTask::spawn(worker_type, Some(worker_id), userid.clone(), true, move |worker| {
         let mut env = BackupEnvironment::new(
-            env_type, username.clone(), worker.clone(), datastore, backup_dir);
+            env_type, userid, worker.clone(), datastore, backup_dir);
 
         env.debug = debug;
         env.last_backup = last_backup;
 
-        env.log(format!("starting new backup on datastore '{}': {:?}", store, path));
+        env.log(format!("starting new {} on datastore '{}': {:?}", worker_type, store, path));
 
         let service = H2Service::new(env.clone(), worker.clone(), &BACKUP_API_ROUTER, debug);
 
         let abort_future = worker.abort_future();
 
         let env2 = env.clone();
-        let env3 = env.clone();
 
-        let req_fut = req_body
+        let mut req_fut = req_body
             .on_upgrade()
             .map_err(Error::from)
             .and_then(move |conn| {
-                env3.debug("protocol upgrade done");
+                env2.debug("protocol upgrade done");
 
                 let mut http = hyper::server::conn::Http::new();
                 http.http2_only(true);
@@ -120,40 +180,53 @@ fn upgrade_to_backup_protocol(
                 let window_size = 32*1024*1024; // max = (1 << 31) - 2
                 http.http2_initial_stream_window_size(window_size);
                 http.http2_initial_connection_window_size(window_size);
+                http.http2_max_frame_size(4*1024*1024);
 
                 http.serve_connection(conn, service)
                     .map_err(Error::from)
             });
-        let abort_future = abort_future
+        let mut abort_future = abort_future
             .map(|_| Err(format_err!("task aborted")));
 
-        use futures::future::Either;
+        async move {
-        future::select(req_fut, abort_future)
+            // keep flock until task ends
-            .map(|res| match res {
+            let _group_guard = _group_guard;
-                Either::Left((Ok(res), _)) => Ok(res),
+            let _snap_guard = _snap_guard;
-                Either::Left((Err(err), _)) => Err(err),
+            let _last_guard = _last_guard;
-                Either::Right((Ok(res), _)) => Ok(res),
+
-                Either::Right((Err(err), _)) => Err(err),
+            let res = select!{
-            })
+                req = req_fut => req,
-            .and_then(move |_result| async move {
+                abrt = abort_future => abrt,
-                env.ensure_finished()?;
+            };
-                env.log("backup finished sucessfully");
+            if benchmark {
-                Ok(())
+                env.log("benchmark finished successfully");
-            })
+                tools::runtime::block_in_place(|| env.remove_backup())?;
-            .then(move |result| async move {
+                return Ok(());
-                if let Err(err) = result {
+            }
-                    match env2.ensure_finished() {
+            match (res, env.ensure_finished()) {
-                        Ok(()) => {}, // ignore error after finish
+                (Ok(_), Ok(())) => {
-                        _ => {
+                    env.log("backup finished successfully");
-                            env2.log(format!("backup failed: {}", err));
+                    Ok(())
-                            env2.log("removing failed backup");
+                },
-                            env2.remove_backup()?;
+                (Err(err), Ok(())) => {
-                            return Err(err);
+                    // ignore errors after finish
-                        }
+                    env.log(format!("backup had errors but finished: {}", err));
-                    }
+                    Ok(())
-                }
+                },
-                Ok(())
+                (Ok(_), Err(err)) => {
-            })
+                    env.log(format!("backup ended and finish failed: {}", err));
+                    env.log("removing unfinished backup");
+                    env.remove_backup()?;
+                    Err(err)
+                },
+                (Err(err), Err(_)) => {
+                    env.log(format!("backup failed: {}", err));
+                    env.log("removing failed backup");
+                    tools::runtime::block_in_place(|| env.remove_backup())?;
+                    Err(err)
+                },
+            }
+        }
     })?;
 
     let response = Response::builder()
@@ -180,7 +253,6 @@ pub const BACKUP_API_SUBDIRS: SubdirMap = &[
     ),
     (
         "dynamic_index", &Router::new()
-            .download(&API_METHOD_DYNAMIC_CHUNK_INDEX)
             .post(&API_METHOD_CREATE_DYNAMIC_INDEX)
             .put(&API_METHOD_DYNAMIC_APPEND)
     ),
@@ -203,10 +275,13 @@ pub const BACKUP_API_SUBDIRS: SubdirMap = &[
     ),
     (
         "fixed_index", &Router::new()
-            .download(&API_METHOD_FIXED_CHUNK_INDEX)
             .post(&API_METHOD_CREATE_FIXED_INDEX)
             .put(&API_METHOD_FIXED_APPEND)
     ),
+    (
+        "previous", &Router::new()
+            .download(&API_METHOD_DOWNLOAD_PREVIOUS)
+    ),
     (
         "speedtest", &Router::new()
             .upload(&API_METHOD_UPLOAD_SPEEDTEST)
@@ -265,6 +340,8 @@ pub const API_METHOD_CREATE_FIXED_INDEX: ApiMethod = ApiMethod::new(
              .minimum(1)
              .schema()
             ),
+            ("reuse-csum", true, &StringSchema::new("If set, compare last backup's \
+                csum and reuse index for incremental backup if it matches.").schema()),
         ]),
     )
 );
@@ -277,10 +354,9 @@ fn create_fixed_index(
 
     let env: &BackupEnvironment = rpcenv.as_ref();
 
-    println!("PARAM: {:?}", param);
-
     let name = tools::required_string_param(&param, "archive-name")?.to_owned();
     let size = tools::required_integer_param(&param, "size")? as usize;
+    let reuse_csum = param["reuse-csum"].as_str();
 
     let archive_name = name.clone();
     if !archive_name.ends_with(".fidx") {
@@ -288,12 +364,49 @@ fn create_fixed_index(
     }
 
     let mut path = env.backup_dir.relative_path();
-    path.push(archive_name);
+    path.push(&archive_name);
 
     let chunk_size = 4096*1024; // todo: ??
 
-    let index = env.datastore.create_fixed_writer(&path, size, chunk_size)?;
+    // do incremental backup if csum is set
-    let wid = env.register_fixed_writer(index, name, size, chunk_size as u32)?;
+    let mut reader = None;
+    let mut incremental = false;
+    if let Some(csum) = reuse_csum {
+        incremental = true;
+        let last_backup = match &env.last_backup {
+            Some(info) => info,
+            None => {
+                bail!("cannot reuse index - no valid previous backup exists");
+            }
+        };
+
+        let mut last_path = last_backup.backup_dir.relative_path();
+        last_path.push(&archive_name);
+
+        let index = match env.datastore.open_fixed_reader(last_path) {
+            Ok(index) => index,
+            Err(_) => {
+                bail!("cannot reuse index - no previous backup exists for archive");
+            }
+        };
+
+        let (old_csum, _) = index.compute_csum();
+        let old_csum = proxmox::tools::digest_to_hex(&old_csum);
+        if old_csum != csum {
+            bail!("expected csum ({}) doesn't match last backup's ({}), cannot do incremental backup",
+                csum, old_csum);
+        }
+
+        reader = Some(index);
+    }
+
+    let mut writer = env.datastore.create_fixed_writer(&path, size, chunk_size)?;
+
+    if let Some(reader) = reader {
+        writer.clone_data_from(&reader)?;
+    }
+
+    let wid = env.register_fixed_writer(writer, name, size, chunk_size as u32, incremental)?;
 
     env.log(format!("created new fixed index {} ({:?})", wid, path));
 
@@ -359,7 +472,7 @@ fn dynamic_append (
 
         env.dynamic_writer_append_chunk(wid, offset, size, &digest)?;
 
-        env.debug(format!("sucessfully added chunk {} to dynamic index {} (offset {}, size {})", digest_str, wid, offset, size));
+        env.debug(format!("successfully added chunk {} to dynamic index {} (offset {}, size {})", digest_str, wid, offset, size));
     }
 
     Ok(Value::Null)
@@ -424,7 +537,7 @@ fn fixed_append (
 
         env.fixed_writer_append_chunk(wid, offset, size, &digest)?;
 
-        env.debug(format!("sucessfully added chunk {} to fixed index {} (offset {}, size {})", digest_str, wid, offset, size));
+        env.debug(format!("successfully added chunk {} to fixed index {} (offset {}, size {})", digest_str, wid, offset, size));
     }
 
     Ok(Value::Null)
@@ -479,7 +592,7 @@ fn close_dynamic_index (
 
     env.dynamic_writer_close(wid, chunk_count, size, csum)?;
 
-    env.log(format!("sucessfully closed dynamic index {}", wid));
+    env.log(format!("successfully closed dynamic index {}", wid));
 
     Ok(Value::Null)
 }
@@ -501,15 +614,15 @@ pub const API_METHOD_CLOSE_FIXED_INDEX: ApiMethod = ApiMethod::new(
             (
                 "chunk-count",
                 false,
-                &IntegerSchema::new("Chunk count. This is used to verify that the server got all chunks.")
+                &IntegerSchema::new("Chunk count. This is used to verify that the server got all chunks. Ignored for incremental backups.")
-                    .minimum(1)
+                    .minimum(0)
                     .schema()
             ),
             (
                 "size",
                 false,
-                &IntegerSchema::new("File size. This is used to verify that the server got all data.")
+                &IntegerSchema::new("File size. This is used to verify that the server got all data. Ignored for incremental backups.")
-                    .minimum(1)
+                    .minimum(0)
                     .schema()
             ),
             ("csum", false, &StringSchema::new("Digest list checksum.").schema()),
@@ -533,7 +646,7 @@ fn close_fixed_index (
 
     env.fixed_writer_close(wid, chunk_count, size, csum)?;
 
-    env.log(format!("sucessfully closed fixed index {}", wid));
+    env.log(format!("successfully closed fixed index {}", wid));
 
     Ok(Value::Null)
 }
@@ -547,26 +660,23 @@ fn finish_backup (
     let env: &BackupEnvironment = rpcenv.as_ref();
 
     env.finish_backup()?;
-    env.log("sucessfully finished backup");
+    env.log("successfully finished backup");
 
     Ok(Value::Null)
 }
 
 #[sortable]
-pub const API_METHOD_DYNAMIC_CHUNK_INDEX: ApiMethod = ApiMethod::new(
+pub const API_METHOD_DOWNLOAD_PREVIOUS: ApiMethod = ApiMethod::new(
-    &ApiHandler::AsyncHttp(&dynamic_chunk_index),
+    &ApiHandler::AsyncHttp(&download_previous),
     &ObjectSchema::new(
-        r###"
+        "Download archive from previous backup.",
-Download the dynamic chunk index from the previous backup.
-Simply returns an empty list if this is the first backup.
-"### ,
         &sorted!([
             ("archive-name", false, &crate::api2::types::BACKUP_ARCHIVE_NAME_SCHEMA)
         ]),
     )
 );
 
-fn dynamic_chunk_index(
+fn download_previous(
     _parts: Parts,
     _req_body: Body,
     param: Value,
@@ -579,130 +689,38 @@ fn dynamic_chunk_index(
 
         let archive_name = tools::required_string_param(&param, "archive-name")?.to_owned();
 
-        if !archive_name.ends_with(".didx") {
-            bail!("wrong archive extension: '{}'", archive_name);
-        }
-
-        let empty_response = {
-            Response::builder()
-                .status(StatusCode::OK)
-                .body(Body::empty())?
-        };
-
         let last_backup = match &env.last_backup {
             Some(info) => info,
-            None => return Ok(empty_response),
+            None => bail!("no valid previous backup"),
         };
 
-        let mut path = last_backup.backup_dir.relative_path();
+        let mut path = env.datastore.snapshot_path(&last_backup.backup_dir);
         path.push(&archive_name);
 
-        let index = match env.datastore.open_dynamic_reader(path) {
+        {
-            Ok(index) => index,
+            let index: Option<Box<dyn IndexFile>> = match archive_type(&archive_name)? {
-            Err(_) => {
+                ArchiveType::FixedIndex => {
-                env.log(format!("there is no last backup for archive '{}'", archive_name));
+                    let index = env.datastore.open_fixed_reader(&path)?;
-                return Ok(empty_response);
+                    Some(Box::new(index))
+                }
+                ArchiveType::DynamicIndex => {
+                    let index = env.datastore.open_dynamic_reader(&path)?;
+                    Some(Box::new(index))
+                }
+                _ => { None }
+            };
+            if let Some(index) = index {
+                env.log(format!("register chunks in '{}' from previous backup.", archive_name));
+
+                for pos in 0..index.index_count() {
+                    let info = index.chunk_info(pos).unwrap();
+                    let size = info.range.end - info.range.start;
+                    env.register_chunk(info.digest, size as u32)?;
+                }
             }
-        };
-
-        env.log(format!("download last backup index for archive '{}'", archive_name));
-
-        let count = index.index_count();
-        for pos in 0..count {
-            let (start, end, digest) = index.chunk_info(pos)?;
-            let size = (end - start) as u32;
-            env.register_chunk(digest, size)?;
         }
 
-        let reader = DigestListEncoder::new(Box::new(index));
+        env.log(format!("download '{}' from previous backup.", archive_name));
-
+        crate::api2::helpers::create_download_response(path).await
-        let stream = WrappedReaderStream::new(reader);
-
-        // fixme: set size, content type?
-        let response = http::Response::builder()
-            .status(200)
-            .body(Body::wrap_stream(stream))?;
-
-        Ok(response)
-    }.boxed()
-}
-
-#[sortable]
-pub const API_METHOD_FIXED_CHUNK_INDEX: ApiMethod = ApiMethod::new(
-    &ApiHandler::AsyncHttp(&fixed_chunk_index),
-    &ObjectSchema::new(
-        r###"
-Download the fixed chunk index from the previous backup.
-Simply returns an empty list if this is the first backup.
-"### ,
-        &sorted!([
-            ("archive-name", false, &crate::api2::types::BACKUP_ARCHIVE_NAME_SCHEMA)
-        ]),
-    )
-);
-
-fn fixed_chunk_index(
-    _parts: Parts,
-    _req_body: Body,
-    param: Value,
-    _info: &ApiMethod,
-    rpcenv: Box<dyn RpcEnvironment>,
-) -> ApiResponseFuture {
-
-    async move {
-        let env: &BackupEnvironment = rpcenv.as_ref();
-
-        let archive_name = tools::required_string_param(&param, "archive-name")?.to_owned();
-
-        if !archive_name.ends_with(".fidx") {
-            bail!("wrong archive extension: '{}'", archive_name);
-        }
-
-        let empty_response = {
-            Response::builder()
-                .status(StatusCode::OK)
-                .body(Body::empty())?
-        };
-
-        let last_backup = match &env.last_backup {
-            Some(info) => info,
-            None => return Ok(empty_response),
-        };
-
-        let mut path = last_backup.backup_dir.relative_path();
-        path.push(&archive_name);
-
-        let index = match env.datastore.open_fixed_reader(path) {
-            Ok(index) => index,
-            Err(_) => {
-                env.log(format!("there is no last backup for archive '{}'", archive_name));
-                return Ok(empty_response);
-            }
-        };
-
-        env.log(format!("download last backup index for archive '{}'", archive_name));
-
-        let count = index.index_count();
-        let image_size = index.index_bytes();
-        for pos in 0..count {
-            let digest = index.index_digest(pos).unwrap();
-            // Note: last chunk can be smaller
-            let start = (pos*index.chunk_size) as u64;
-            let mut end = start + index.chunk_size as u64;
-            if end > image_size { end = image_size; }
-            let size = (end - start) as u32;
-            env.register_chunk(*digest, size)?;
-        }
-
-        let reader = DigestListEncoder::new(Box::new(index));
-
-        let stream = WrappedReaderStream::new(reader);
-
-        // fixme: set size, content type?
-        let response = http::Response::builder()
-            .status(200)
-            .body(Body::wrap_stream(stream))?;
-
-        Ok(response)
     }.boxed()
 }

src/api2/backup/environment.rs

@@ -1,18 +1,21 @@
-use failure::*;
+use anyhow::{bail, format_err, Error};
 use std::sync::{Arc, Mutex};
 use std::collections::HashMap;
 
-use serde_json::Value;
+use ::serde::{Serialize};
+use serde_json::{json, Value};
 
 use proxmox::tools::digest_to_hex;
 use proxmox::tools::fs::{replace_file, CreateOptions};
 use proxmox::api::{RpcEnvironment, RpcEnvironmentType};
 
-use crate::server::WorkerTask;
+use crate::api2::types::Userid;
 use crate::backup::*;
+use crate::server::WorkerTask;
 use crate::server::formatter::*;
 use hyper::{Body, Response};
 
+#[derive(Copy, Clone, Serialize)]
 struct UploadStatistic {
     count: u64,
     size: u64,
@@ -31,6 +34,19 @@ impl UploadStatistic {
     }
 }
 
+impl std::ops::Add for UploadStatistic {
+    type Output = Self;
+
+    fn add(self, other: Self) -> Self {
+        Self {
+            count: self.count + other.count,
+            size: self.size + other.size,
+            compressed_size: self.compressed_size + other.compressed_size,
+            duplicates: self.duplicates + other.duplicates,
+        }
+    }
+}
+
 struct DynamicWriterState {
     name: String,
     index: DynamicIndexWriter,
@@ -47,15 +63,21 @@ struct FixedWriterState {
     chunk_count: u64,
     small_chunk_count: usize, // allow 0..1 small chunks (last chunk may be smaller)
     upload_stat: UploadStatistic,
+    incremental: bool,
 }
 
+// key=digest, value=length
+type KnownChunksMap = HashMap<[u8;32], u32>;
+
 struct SharedBackupState {
     finished: bool,
     uid_counter: usize,
-    file_counter: usize, // sucessfully uploaded files
+    file_counter: usize, // successfully uploaded files
     dynamic_writers: HashMap<usize, DynamicWriterState>,
     fixed_writers: HashMap<usize, FixedWriterState>,
-    known_chunks: HashMap<[u8;32], u32>,
+    known_chunks: KnownChunksMap,
+    backup_size: u64, // sums up size of all files
+    backup_stat: UploadStatistic,
 }
 
 impl SharedBackupState {
@@ -80,8 +102,8 @@ impl SharedBackupState {
 #[derive(Clone)]
 pub struct BackupEnvironment {
     env_type: RpcEnvironmentType,
-    result_attributes: HashMap<String, Value>,
+    result_attributes: Value,
-    user: String,
+    user: Userid,
     pub debug: bool,
     pub formatter: &'static OutputFormatter,
     pub worker: Arc<WorkerTask>,
@@ -94,7 +116,7 @@ pub struct BackupEnvironment {
 impl BackupEnvironment {
     pub fn new(
         env_type: RpcEnvironmentType,
-        user: String,
+        user: Userid,
         worker: Arc<WorkerTask>,
         datastore: Arc<DataStore>,
         backup_dir: BackupDir,
@@ -107,10 +129,12 @@ impl BackupEnvironment {
             dynamic_writers: HashMap::new(),
             fixed_writers: HashMap::new(),
             known_chunks: HashMap::new(),
+            backup_size: 0,
+            backup_stat: UploadStatistic::new(),
         };
 
         Self {
-            result_attributes: HashMap::new(),
+            result_attributes: json!({}),
             env_type,
             user,
             worker,
@@ -237,7 +261,7 @@ impl BackupEnvironment {
     }
 
     /// Store the writer with an unique ID
-    pub fn register_fixed_writer(&self, index: FixedIndexWriter, name: String, size: usize, chunk_size: u32) -> Result<usize, Error> {
+    pub fn register_fixed_writer(&self, index: FixedIndexWriter, name: String, size: usize, chunk_size: u32, incremental: bool) -> Result<usize, Error> {
         let mut state = self.state.lock().unwrap();
 
         state.ensure_unfinished()?;
@@ -245,7 +269,7 @@ impl BackupEnvironment {
         let uid = state.next_uid();
 
         state.fixed_writers.insert(uid, FixedWriterState {
-            index, name, chunk_count: 0, size, chunk_size, small_chunk_count: 0, upload_stat: UploadStatistic::new(),
+            index, name, chunk_count: 0, size, chunk_size, small_chunk_count: 0, upload_stat: UploadStatistic::new(), incremental,
         });
 
         Ok(uid)
@@ -310,7 +334,13 @@ impl BackupEnvironment {
 
         self.log(format!("Upload size: {} ({}%)", upload_stat.size, (upload_stat.size*100)/size));
 
-        let client_side_duplicates = chunk_count - upload_stat.count;
+        // account for zero chunk, which might be uploaded but never used
+        let client_side_duplicates = if chunk_count < upload_stat.count {
+            0
+        } else {
+            chunk_count - upload_stat.count
+        };
+
         let server_side_duplicates = upload_stat.duplicates;
 
         if (client_side_duplicates + server_side_duplicates) > 0 {
@@ -346,7 +376,6 @@ impl BackupEnvironment {
 
         let expected_csum = data.index.close()?;
 
-        println!("server checksum {:?} client: {:?}", expected_csum, csum);
         if csum != expected_csum {
             bail!("dynamic writer '{}' close failed - got unexpected checksum", data.name);
         }
@@ -354,6 +383,8 @@ impl BackupEnvironment {
         self.log_upload_stat(&data.name, &csum, &uuid, size, chunk_count, &data.upload_stat);
 
         state.file_counter += 1;
+        state.backup_size += size;
+        state.backup_stat = state.backup_stat + data.upload_stat;
 
         Ok(())
     }
@@ -373,21 +404,21 @@ impl BackupEnvironment {
             bail!("fixed writer '{}' close failed - received wrong number of chunk ({} != {})", data.name, data.chunk_count, chunk_count);
         }
 
-        let expected_count = data.index.index_length();
+        if !data.incremental {
+            let expected_count = data.index.index_length();
 
-        if chunk_count != (expected_count as u64) {
+            if chunk_count != (expected_count as u64) {
-            bail!("fixed writer '{}' close failed - unexpected chunk count ({} != {})", data.name, expected_count, chunk_count);
+                bail!("fixed writer '{}' close failed - unexpected chunk count ({} != {})", data.name, expected_count, chunk_count);
-        }
+            }
 
-        if size != (data.size as u64) {
+            if size != (data.size as u64) {
-            bail!("fixed writer '{}' close failed - unexpected file size ({} != {})", data.name, data.size, size);
+                bail!("fixed writer '{}' close failed - unexpected file size ({} != {})", data.name, data.size, size);
+            }
         }
 
         let uuid = data.index.uuid;
-
         let expected_csum = data.index.close()?;
 
-        println!("server checksum {:?} client: {:?}", expected_csum, csum);
         if csum != expected_csum {
             bail!("fixed writer '{}' close failed - got unexpected checksum", data.name);
         }
@@ -395,6 +426,8 @@ impl BackupEnvironment {
         self.log_upload_stat(&data.name, &expected_csum, &uuid, size, chunk_count, &data.upload_stat);
 
         state.file_counter += 1;
+        state.backup_size += size;
+        state.backup_stat = state.backup_stat + data.upload_stat;
 
         Ok(())
     }
@@ -408,9 +441,8 @@ impl BackupEnvironment {
         let blob_len = data.len();
         let orig_len = data.len(); // fixme:
 
-        let blob = DataBlob::from_raw(data)?;
+        // always verify blob/CRC at server side
-        // always verify CRC at server side
+        let blob = DataBlob::load_from_reader(&mut &data[..])?;
-        blob.verify_crc()?;
 
         let raw_data = blob.raw_data();
         replace_file(&path, raw_data, CreateOptions::new())?;
@@ -419,6 +451,8 @@ impl BackupEnvironment {
 
         let mut state = self.state.lock().unwrap();
         state.file_counter += 1;
+        state.backup_size += orig_len as u64;
+        state.backup_stat.size += blob_len as u64;
 
         Ok(())
     }
@@ -426,13 +460,11 @@ impl BackupEnvironment {
     /// Mark backup as finished
     pub fn finish_backup(&self) -> Result<(), Error> {
         let mut state = self.state.lock().unwrap();
-        // test if all writer are correctly closed
 
         state.ensure_unfinished()?;
 
-        state.finished = true;
+        // test if all writer are correctly closed
-
+        if state.dynamic_writers.len() != 0 || state.fixed_writers.len() != 0 {
-        if state.dynamic_writers.len() != 0 {
             bail!("found open index writer - unable to finish backup");
         }
 
@@ -440,6 +472,30 @@ impl BackupEnvironment {
             bail!("backup does not contain valid files (file count == 0)");
         }
 
+        // check manifest
+        let mut manifest = self.datastore.load_manifest_json(&self.backup_dir)
+            .map_err(|err| format_err!("unable to load manifest blob - {}", err))?;
+
+        let stats = serde_json::to_value(state.backup_stat)?;
+
+        manifest["unprotected"]["chunk_upload_stats"] = stats;
+
+        self.datastore.store_manifest(&self.backup_dir, manifest)
+            .map_err(|err| format_err!("unable to store manifest blob - {}", err))?;
+
+        if let Some(base) = &self.last_backup {
+            let path = self.datastore.snapshot_path(&base.backup_dir);
+            if !path.exists() {
+                bail!(
+                    "base snapshot {} was removed during backup, cannot finish as chunks might be missing",
+                    base.backup_dir
+                );
+            }
+        }
+
+        // marks the backup as successful
+        state.finished = true;
+
         Ok(())
     }
 
@@ -472,7 +528,7 @@ impl BackupEnvironment {
         let mut state = self.state.lock().unwrap();
         state.finished = true;
 
-        self.datastore.remove_backup_dir(&self.backup_dir)?;
+        self.datastore.remove_backup_dir(&self.backup_dir, true)?;
 
         Ok(())
     }
@@ -480,12 +536,12 @@ impl BackupEnvironment {
 
 impl RpcEnvironment for BackupEnvironment {
 
-    fn set_result_attrib(&mut self, name: &str, value: Value) {
+    fn result_attrib_mut(&mut self) -> &mut Value {
-        self.result_attributes.insert(name.into(), value);
+        &mut self.result_attributes
     }
 
-    fn get_result_attrib(&self, name: &str) -> Option<&Value> {
+    fn result_attrib(&self) -> &Value {
-        self.result_attributes.get(name)
+        &self.result_attributes
     }
 
     fn env_type(&self) -> RpcEnvironmentType {
@@ -497,7 +553,7 @@ impl RpcEnvironment for BackupEnvironment {
     }
 
     fn get_user(&self) -> Option<String> {
-        Some(self.user.clone())
+        Some(self.user.to_string())
     }
 }
 

src/api2/backup/upload_chunk.rs

@@ -2,7 +2,7 @@ use std::pin::Pin;
 use std::sync::Arc;
 use std::task::{Context, Poll};
 
-use failure::*;
+use anyhow::{bail, format_err, Error};
 use futures::*;
 use hyper::Body;
 use hyper::http::request::Parts;
@@ -61,12 +61,15 @@ impl Future for UploadChunk {
                         let (is_duplicate, compressed_size) = match proxmox::try_block! {
                             let mut chunk = DataBlob::from_raw(raw_data)?;
 
-                            chunk.verify_unencrypted(this.size as usize, &this.digest)?;
+                            tools::runtime::block_in_place(|| {
+                                chunk.verify_unencrypted(this.size as usize, &this.digest)?;
 
-                            // always comput CRC at server side
+                                // always comput CRC at server side
-                            chunk.set_crc(chunk.compute_crc());
+                                chunk.set_crc(chunk.compute_crc());
+
+                                this.store.insert_chunk(&chunk, &this.digest)
+                            })
 
-                            this.store.insert_chunk(&chunk, &this.digest)
                         } {
                             Ok(res) => res,
                             Err(err) => break err,
@@ -243,7 +246,7 @@ pub const API_METHOD_UPLOAD_BLOB: ApiMethod = ApiMethod::new(
         &sorted!([
             ("file-name", false, &crate::api2::types::BACKUP_ARCHIVE_NAME_SCHEMA),
             ("encoded-size", false, &IntegerSchema::new("Encoded blob size.")
-             .minimum((std::mem::size_of::<DataBlobHeader>() as isize) +1)
+             .minimum(std::mem::size_of::<DataBlobHeader>() as isize)
              .maximum(1024*1024*16+(std::mem::size_of::<EncryptedDataBlobHeader>() as isize))
              .schema()
             )

src/api2/config.rs

@@ -3,10 +3,12 @@ use proxmox::list_subdirs_api_method;
 
 pub mod datastore;
 pub mod remote;
+pub mod sync;
 
 const SUBDIRS: SubdirMap = &[
     ("datastore", &datastore::ROUTER),
     ("remote", &remote::ROUTER),
+    ("sync", &sync::ROUTER),
 ];
 
 pub const ROUTER: Router = Router::new()

src/api2/config/datastore.rs

@@ -1,13 +1,17 @@
 use std::path::PathBuf;
 
-use failure::*;
+use anyhow::{bail, Error};
 use serde_json::Value;
+use ::serde::{Deserialize, Serialize};
 
-use proxmox::api::{api, ApiMethod, Router, RpcEnvironment};
+use proxmox::api::{api, Router, RpcEnvironment, Permission};
+use proxmox::tools::fs::open_file_locked;
 
 use crate::api2::types::*;
 use crate::backup::*;
-use crate::config::datastore;
+use crate::config::cached_user_info::CachedUserInfo;
+use crate::config::datastore::{self, DataStoreConfig, DIR_NAME_SCHEMA};
+use crate::config::acl::{PRIV_DATASTORE_ALLOCATE, PRIV_DATASTORE_AUDIT, PRIV_DATASTORE_MODIFY};
 
 #[api(
     input: {
@@ -16,23 +20,39 @@ use crate::config::datastore;
     returns: {
         description: "List the configured datastores (with config digest).",
         type: Array,
-        items: {
+        items: { type: datastore::DataStoreConfig },
-            type: datastore::DataStoreConfig,
+    },
-        },
+    access: {
+        permission: &Permission::Anybody,
     },
 )]
 /// List all datastores
 pub fn list_datastores(
     _param: Value,
-    _info: &ApiMethod,
+    mut rpcenv: &mut dyn RpcEnvironment,
-    _rpcenv: &mut dyn RpcEnvironment,
+) -> Result<Vec<DataStoreConfig>, Error> {
-) -> Result<Value, Error> {
 
     let (config, digest) = datastore::config()?;
 
-    Ok(config.convert_to_array("name", Some(&digest), &[]))
+    let userid: Userid = rpcenv.get_user().unwrap().parse()?;
+    let user_info = CachedUserInfo::new()?;
+
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
+
+    let list:Vec<DataStoreConfig> = config.convert_to_typed_array("datastore")?;
+    let filter_by_privs = |store: &DataStoreConfig| {
+        let user_privs = user_info.lookup_privs(&userid, &["datastore", &store.name]);
+        (user_privs & PRIV_DATASTORE_AUDIT) != 0
+    };
+
+    Ok(list.into_iter().filter(filter_by_privs).collect())
 }
 
+
+// fixme: impl. const fn get_object_schema(datastore::DataStoreConfig::API_SCHEMA),
+// but this need support for match inside const fn
+// see: https://github.com/rust-lang/rust/issues/49146
+
 #[api(
     protected: true,
     input: {
@@ -40,38 +60,81 @@ pub fn list_datastores(
             name: {
                 schema: DATASTORE_SCHEMA,
             },
+            path: {
+                schema: DIR_NAME_SCHEMA,
+            },
             comment: {
                 optional: true,
                 schema: SINGLE_LINE_COMMENT_SCHEMA,
             },
-            path: {
+            "gc-schedule": {
-                schema: datastore::DIR_NAME_SCHEMA,
+                optional: true,
+                schema: GC_SCHEDULE_SCHEMA,
+            },
+            "prune-schedule": {
+                optional: true,
+                schema: PRUNE_SCHEDULE_SCHEMA,
+            },
+            "verify-schedule": {
+                optional: true,
+                schema: VERIFY_SCHEDULE_SCHEMA,
+            },
+            "keep-last": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_LAST,
+            },
+            "keep-hourly": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_HOURLY,
+            },
+            "keep-daily": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_DAILY,
+            },
+            "keep-weekly": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_WEEKLY,
+            },
+            "keep-monthly": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_MONTHLY,
+            },
+            "keep-yearly": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_YEARLY,
             },
         },
     },
+    access: {
+        permission: &Permission::Privilege(&["datastore"], PRIV_DATASTORE_ALLOCATE, false),
+    },
 )]
 /// Create new datastore config.
-pub fn create_datastore(name: String, param: Value) -> Result<(), Error> {
+pub fn create_datastore(param: Value) -> Result<(), Error> {
 
-    let _lock = crate::tools::open_file_locked(datastore::DATASTORE_CFG_LOCKFILE, std::time::Duration::new(10, 0))?;
+    let _lock = open_file_locked(datastore::DATASTORE_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
 
     let datastore: datastore::DataStoreConfig = serde_json::from_value(param.clone())?;
 
     let (mut config, _digest) = datastore::config()?;
 
-    if let Some(_) = config.sections.get(&name) {
+    if let Some(_) = config.sections.get(&datastore.name) {
-        bail!("datastore '{}' already exists.", name);
+        bail!("datastore '{}' already exists.", datastore.name);
     }
 
     let path: PathBuf = datastore.path.clone().into();
 
     let backup_user = crate::backup::backup_user()?;
-    let _store = ChunkStore::create(&name, path, backup_user.uid, backup_user.gid)?;
+    let _store = ChunkStore::create(&datastore.name, path, backup_user.uid, backup_user.gid)?;
 
-    config.set_data(&name, "datastore", &datastore)?;
+    config.set_data(&datastore.name, "datastore", &datastore)?;
 
     datastore::save_config(&config)?;
 
+    crate::config::jobstate::create_state_file("prune", &datastore.name)?;
+    crate::config::jobstate::create_state_file("garbage_collection", &datastore.name)?;
+    crate::config::jobstate::create_state_file("verify", &datastore.name)?;
+
     Ok(())
 }
 
@@ -87,14 +150,49 @@ pub fn create_datastore(name: String, param: Value) -> Result<(), Error> {
         description: "The datastore configuration (with config digest).",
         type: datastore::DataStoreConfig,
     },
+    access: {
+        permission: &Permission::Privilege(&["datastore", "{name}"], PRIV_DATASTORE_AUDIT, false),
+    },
 )]
 /// Read a datastore configuration.
-pub fn read_datastore(name: String) -> Result<Value, Error> {
+pub fn read_datastore(
+    name: String,
+    mut rpcenv: &mut dyn RpcEnvironment,
+) -> Result<DataStoreConfig, Error> {
     let (config, digest) = datastore::config()?;
-    let mut data = config.lookup_json("datastore", &name)?;
+
-    data.as_object_mut().unwrap()
+    let store_config = config.lookup("datastore", &name)?;
-        .insert("digest".into(), proxmox::tools::digest_to_hex(&digest).into());
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
-    Ok(data)
+
+    Ok(store_config)
+}
+
+#[api()]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all="kebab-case")]
+#[allow(non_camel_case_types)]
+/// Deletable property name
+pub enum DeletableProperty {
+    /// Delete the comment property.
+    comment,
+    /// Delete the garbage collection schedule.
+    gc_schedule,
+    /// Delete the prune job schedule.
+    prune_schedule,
+    /// Delete the verify schedule property
+    verify_schedule,
+    /// Delete the keep-last property
+    keep_last,
+    /// Delete the keep-hourly property
+    keep_hourly,
+    /// Delete the keep-daily property
+    keep_daily,
+    /// Delete the keep-weekly property
+    keep_weekly,
+    /// Delete the keep-monthly property
+    keep_monthly,
+    /// Delete the keep-yearly property
+    keep_yearly,
 }
 
 #[api(
@@ -108,21 +206,78 @@ pub fn read_datastore(name: String) -> Result<Value, Error> {
                 optional: true,
                 schema: SINGLE_LINE_COMMENT_SCHEMA,
             },
+            "gc-schedule": {
+                optional: true,
+                schema: GC_SCHEDULE_SCHEMA,
+            },
+            "prune-schedule": {
+                optional: true,
+                schema: PRUNE_SCHEDULE_SCHEMA,
+            },
+            "verify-schedule": {
+                optional: true,
+                schema: VERIFY_SCHEDULE_SCHEMA,
+            },
+            "keep-last": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_LAST,
+            },
+            "keep-hourly": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_HOURLY,
+            },
+            "keep-daily": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_DAILY,
+            },
+            "keep-weekly": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_WEEKLY,
+            },
+            "keep-monthly": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_MONTHLY,
+            },
+            "keep-yearly": {
+                optional: true,
+                schema: PRUNE_SCHEMA_KEEP_YEARLY,
+            },
+            delete: {
+                description: "List of properties to delete.",
+                type: Array,
+                optional: true,
+                items: {
+                    type: DeletableProperty,
+                }
+            },
             digest: {
                 optional: true,
                 schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
             },
         },
     },
+    access: {
+        permission: &Permission::Privilege(&["datastore", "{name}"], PRIV_DATASTORE_MODIFY, false),
+    },
 )]
-/// Create new datastore config.
+/// Update datastore config.
 pub fn update_datastore(
     name: String,
     comment: Option<String>,
+    gc_schedule: Option<String>,
+    prune_schedule: Option<String>,
+    verify_schedule: Option<String>,
+    keep_last: Option<u64>,
+    keep_hourly: Option<u64>,
+    keep_daily: Option<u64>,
+    keep_weekly: Option<u64>,
+    keep_monthly: Option<u64>,
+    keep_yearly: Option<u64>,
+    delete: Option<Vec<DeletableProperty>>,
     digest: Option<String>,
 ) -> Result<(), Error> {
 
-    let _lock = crate::tools::open_file_locked(datastore::DATASTORE_CFG_LOCKFILE, std::time::Duration::new(10, 0))?;
+    let _lock = open_file_locked(datastore::DATASTORE_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
 
     // pass/compare digest
     let (mut config, expected_digest) = datastore::config()?;
@@ -134,6 +289,23 @@ pub fn update_datastore(
 
     let mut data: datastore::DataStoreConfig = config.lookup("datastore", &name)?;
 
+     if let Some(delete) = delete {
+        for delete_prop in delete {
+            match delete_prop {
+                DeletableProperty::comment => { data.comment = None; },
+                DeletableProperty::gc_schedule => { data.gc_schedule = None; },
+                DeletableProperty::prune_schedule => { data.prune_schedule = None; },
+                DeletableProperty::verify_schedule => { data.verify_schedule = None; },
+                DeletableProperty::keep_last => { data.keep_last = None; },
+                DeletableProperty::keep_hourly => { data.keep_hourly = None; },
+                DeletableProperty::keep_daily => { data.keep_daily = None; },
+                DeletableProperty::keep_weekly => { data.keep_weekly = None; },
+                DeletableProperty::keep_monthly => { data.keep_monthly = None; },
+                DeletableProperty::keep_yearly => { data.keep_yearly = None; },
+            }
+        }
+    }
+
     if let Some(comment) = comment {
         let comment = comment.trim().to_string();
         if comment.is_empty() {
@@ -143,10 +315,49 @@ pub fn update_datastore(
         }
     }
 
+    let mut gc_schedule_changed = false;
+    if gc_schedule.is_some() {
+        gc_schedule_changed = data.gc_schedule != gc_schedule;
+        data.gc_schedule = gc_schedule;
+    }
+
+    let mut prune_schedule_changed = false;
+    if prune_schedule.is_some() {
+        prune_schedule_changed = data.prune_schedule != prune_schedule;
+        data.prune_schedule = prune_schedule;
+    }
+
+    let mut verify_schedule_changed = false;
+    if verify_schedule.is_some() {
+        verify_schedule_changed = data.verify_schedule != verify_schedule;
+        data.verify_schedule = verify_schedule;
+    }
+
+    if keep_last.is_some() { data.keep_last = keep_last; }
+    if keep_hourly.is_some() { data.keep_hourly = keep_hourly; }
+    if keep_daily.is_some() { data.keep_daily = keep_daily; }
+    if keep_weekly.is_some() { data.keep_weekly = keep_weekly; }
+    if keep_monthly.is_some() { data.keep_monthly = keep_monthly; }
+    if keep_yearly.is_some() { data.keep_yearly = keep_yearly; }
+
     config.set_data(&name, "datastore", &data)?;
 
     datastore::save_config(&config)?;
 
+    // we want to reset the statefiles, to avoid an immediate action in some cases
+    // (e.g. going from monthly to weekly in the second week of the month)
+    if gc_schedule_changed {
+        crate::config::jobstate::create_state_file("garbage_collection", &name)?;
+    }
+
+    if prune_schedule_changed {
+        crate::config::jobstate::create_state_file("prune", &name)?;
+    }
+
+    if verify_schedule_changed {
+        crate::config::jobstate::create_state_file("verify", &name)?;
+    }
+
     Ok(())
 }
 
@@ -157,16 +368,27 @@ pub fn update_datastore(
             name: {
                 schema: DATASTORE_SCHEMA,
             },
+            digest: {
+                optional: true,
+                schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
+            },
         },
     },
+    access: {
+        permission: &Permission::Privilege(&["datastore", "{name}"], PRIV_DATASTORE_ALLOCATE, false),
+    },
 )]
 /// Remove a datastore configuration.
-pub fn delete_datastore(name: String) -> Result<(), Error> {
+pub fn delete_datastore(name: String, digest: Option<String>) -> Result<(), Error> {
 
-    // fixme: locking ?
+    let _lock = open_file_locked(datastore::DATASTORE_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
-    // fixme: check digest ?
 
-    let (mut config, _digest) = datastore::config()?;
+    let (mut config, expected_digest) = datastore::config()?;
+
+    if let Some(ref digest) = digest {
+        let digest = proxmox::tools::hex_to_digest(digest)?;
+        crate::tools::detect_modified_configuration_file(&digest, &expected_digest)?;
+    }
 
     match config.sections.get(&name) {
         Some(_) => { config.sections.remove(&name); },
@@ -175,6 +397,11 @@ pub fn delete_datastore(name: String) -> Result<(), Error> {
 
     datastore::save_config(&config)?;
 
+    // ignore errors
+    let _ = crate::config::jobstate::remove_state_file("prune", &name);
+    let _ = crate::config::jobstate::remove_state_file("garbage_collection", &name);
+    let _ = crate::config::jobstate::remove_state_file("verify", &name);
+
     Ok(())
 }
 

src/api2/config/remote.rs

@@ -1,10 +1,14 @@
-use failure::*;
+use anyhow::{bail, Error};
 use serde_json::Value;
+use ::serde::{Deserialize, Serialize};
+use base64;
 
-use proxmox::api::{api, ApiMethod, Router, RpcEnvironment};
+use proxmox::api::{api, ApiMethod, Router, RpcEnvironment, Permission};
+use proxmox::tools::fs::open_file_locked;
 
 use crate::api2::types::*;
 use crate::config::remote;
+use crate::config::acl::{PRIV_REMOTE_AUDIT, PRIV_REMOTE_MODIFY};
 
 #[api(
     input: {
@@ -14,42 +18,32 @@ use crate::config::remote;
         description: "The list of configured remotes (with config digest).",
         type: Array,
         items: {
-            type: Object,
+            type: remote::Remote,
             description: "Remote configuration (without password).",
-            properties: {
-                name: {
-                    schema: REMOTE_ID_SCHEMA,
-                },
-                comment: {
-                    optional: true,
-                    schema: SINGLE_LINE_COMMENT_SCHEMA,
-                },
-                host: {
-                    schema: DNS_NAME_OR_IP_SCHEMA,
-                },
-                userid: {
-                    schema: PROXMOX_USER_ID_SCHEMA,
-                },
-                fingerprint: {
-                    optional: true,
-                    schema: CERT_FINGERPRINT_SHA256_SCHEMA,
-                },
-            },
         },
     },
+    access: {
+        permission: &Permission::Privilege(&["remote"], PRIV_REMOTE_AUDIT, false),
+    },
 )]
 /// List all remotes
 pub fn list_remotes(
     _param: Value,
     _info: &ApiMethod,
-    _rpcenv: &mut dyn RpcEnvironment,
+    mut rpcenv: &mut dyn RpcEnvironment,
-) -> Result<Value, Error> {
+) -> Result<Vec<remote::Remote>, Error> {
 
     let (config, digest) = remote::config()?;
 
-    let value = config.convert_to_array("name", Some(&digest), &["password"]);
+    let mut list: Vec<remote::Remote> = config.convert_to_typed_array("remote")?;
-  
+
-    Ok(value.into())
+    // don't return password in api
+    for remote in &mut list {
+        remote.password = "".to_string();
+    }
+
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
+    Ok(list)
 }
 
 #[api(
@@ -66,8 +60,14 @@ pub fn list_remotes(
             host: {
                 schema: DNS_NAME_OR_IP_SCHEMA,
             },
+            port: {
+                description: "The (optional) port.",
+                type: u16,
+                optional: true,
+                default: 8007,
+            },
             userid: {
-                schema: PROXMOX_USER_ID_SCHEMA,
+                type: Userid,
             },
             password: {
                 schema: remote::REMOTE_PASSWORD_SCHEMA,
@@ -78,21 +78,26 @@ pub fn list_remotes(
             },
         },
     },
+    access: {
+        permission: &Permission::Privilege(&["remote"], PRIV_REMOTE_MODIFY, false),
+    },
 )]
 /// Create new remote.
-pub fn create_remote(name: String, param: Value) -> Result<(), Error> {
+pub fn create_remote(password: String, param: Value) -> Result<(), Error> {
 
-    let _lock = crate::tools::open_file_locked(remote::REMOTE_CFG_LOCKFILE, std::time::Duration::new(10, 0))?;
+    let _lock = open_file_locked(remote::REMOTE_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
 
-    let remote: remote::Remote = serde_json::from_value(param.clone())?;
+    let mut data = param.clone();
+    data["password"] = Value::from(base64::encode(password.as_bytes()));
+    let remote: remote::Remote = serde_json::from_value(data)?;
 
     let (mut config, _digest) = remote::config()?;
 
-    if let Some(_) = config.sections.get(&name) {
+    if let Some(_) = config.sections.get(&remote.name) {
-        bail!("remote '{}' already exists.", name);
+        bail!("remote '{}' already exists.", remote.name);
     }
 
-    config.set_data(&name, "remote", &remote)?;
+    config.set_data(&remote.name, "remote", &remote)?;
 
     remote::save_config(&config)?;
 
@@ -111,16 +116,36 @@ pub fn create_remote(name: String, param: Value) -> Result<(), Error> {
         description: "The remote configuration (with config digest).",
         type: remote::Remote,
     },
+    access: {
+        permission: &Permission::Privilege(&["remote", "{name}"], PRIV_REMOTE_AUDIT, false),
+    }
 )]
 /// Read remote configuration data.
-pub fn read_remote(name: String) -> Result<Value, Error> {
+pub fn read_remote(
+    name: String,
+    _info: &ApiMethod,
+    mut rpcenv: &mut dyn RpcEnvironment,
+) -> Result<remote::Remote, Error> {
     let (config, digest) = remote::config()?;
-    let mut data = config.lookup_json("remote", &name)?;
+    let mut data: remote::Remote = config.lookup("remote", &name)?;
-    data.as_object_mut().unwrap()
+    data.password = "".to_string(); // do not return password in api
-        .insert("digest".into(), proxmox::tools::digest_to_hex(&digest).into());
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
     Ok(data)
 }
 
+#[api()]
+#[derive(Serialize, Deserialize)]
+#[allow(non_camel_case_types)]
+/// Deletable property name
+pub enum DeletableProperty {
+    /// Delete the comment property.
+    comment,
+    /// Delete the fingerprint property.
+    fingerprint,
+    /// Delete the port property.
+    port,
+}
+
 #[api(
     protected: true,
     input: {
@@ -136,9 +161,14 @@ pub fn read_remote(name: String) -> Result<Value, Error> {
                 optional: true,
                 schema: DNS_NAME_OR_IP_SCHEMA,
             },
+            port: {
+                description: "The (optional) port.",
+                type: u16,
+                optional: true,
+            },
             userid: {
                 optional: true,
-               schema: PROXMOX_USER_ID_SCHEMA,
+                type: Userid,
             },
             password: {
                 optional: true,
@@ -148,25 +178,38 @@ pub fn read_remote(name: String) -> Result<Value, Error> {
                 optional: true,
                 schema: CERT_FINGERPRINT_SHA256_SCHEMA,
             },
+            delete: {
+                description: "List of properties to delete.",
+                type: Array,
+                optional: true,
+                items: {
+                    type: DeletableProperty,
+                }
+            },
             digest: {
                 optional: true,
                 schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
             },
         },
     },
+    access: {
+        permission: &Permission::Privilege(&["remote", "{name}"], PRIV_REMOTE_MODIFY, false),
+    },
 )]
 /// Update remote configuration.
 pub fn update_remote(
     name: String,
     comment: Option<String>,
     host: Option<String>,
-    userid: Option<String>,
+    port: Option<u16>,
+    userid: Option<Userid>,
     password: Option<String>,
     fingerprint: Option<String>,
+    delete: Option<Vec<DeletableProperty>>,
     digest: Option<String>,
 ) -> Result<(), Error> {
 
-    let _lock = crate::tools::open_file_locked(remote::REMOTE_CFG_LOCKFILE, std::time::Duration::new(10, 0))?;
+    let _lock = open_file_locked(remote::REMOTE_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
 
     let (mut config, expected_digest) = remote::config()?;
 
@@ -177,6 +220,16 @@ pub fn update_remote(
 
     let mut data: remote::Remote = config.lookup("remote", &name)?;
 
+    if let Some(delete) = delete {
+        for delete_prop in delete {
+            match delete_prop {
+                DeletableProperty::comment => { data.comment = None; },
+                DeletableProperty::fingerprint => { data.fingerprint = None; },
+                DeletableProperty::port => { data.port = None; },
+            }
+        }
+    }
+
     if let Some(comment) = comment {
         let comment = comment.trim().to_string();
         if comment.is_empty() {
@@ -186,10 +239,10 @@ pub fn update_remote(
         }
     }
     if let Some(host) = host { data.host = host; }
+    if port.is_some() { data.port = port; }
     if let Some(userid) = userid { data.userid = userid; }
     if let Some(password) = password { data.password = password; }
 
-    // fixme: howto delete a fingeprint?
     if let Some(fingerprint) = fingerprint { data.fingerprint = Some(fingerprint); }
 
     config.set_data(&name, "remote", &data)?;
@@ -206,22 +259,35 @@ pub fn update_remote(
             name: {
                 schema: REMOTE_ID_SCHEMA,
             },
+            digest: {
+                optional: true,
+                schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
+            },
         },
     },
+    access: {
+        permission: &Permission::Privilege(&["remote", "{name}"], PRIV_REMOTE_MODIFY, false),
+    },
 )]
 /// Remove a remote from the configuration file.
-pub fn delete_remote(name: String) -> Result<(), Error> {
+pub fn delete_remote(name: String, digest: Option<String>) -> Result<(), Error> {
 
-    // fixme: locking ?
+    let _lock = open_file_locked(remote::REMOTE_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
-    // fixme: check digest ?
 
-    let (mut config, _digest) = remote::config()?;
+    let (mut config, expected_digest) = remote::config()?;
+
+    if let Some(ref digest) = digest {
+        let digest = proxmox::tools::hex_to_digest(digest)?;
+        crate::tools::detect_modified_configuration_file(&digest, &expected_digest)?;
+    }
 
     match config.sections.get(&name) {
         Some(_) => { config.sections.remove(&name); },
         None => bail!("remote '{}' does not exist.", name),
     }
 
+    remote::save_config(&config)?;
+
     Ok(())
 }
 

src/api2/config/sync.rs

@@ -0,0 +1,282 @@
+use anyhow::{bail, Error};
+use serde_json::Value;
+use ::serde::{Deserialize, Serialize};
+
+use proxmox::api::{api, Router, RpcEnvironment};
+use proxmox::tools::fs::open_file_locked;
+
+use crate::api2::types::*;
+use crate::config::sync::{self, SyncJobConfig};
+
+// fixme: add access permissions
+
+#[api(
+    input: {
+        properties: {},
+    },
+    returns: {
+        description: "List configured jobs.",
+        type: Array,
+        items: { type: sync::SyncJobConfig },
+    },
+)]
+/// List all sync jobs
+pub fn list_sync_jobs(
+    _param: Value,
+    mut rpcenv: &mut dyn RpcEnvironment,
+) -> Result<Vec<SyncJobConfig>, Error> {
+
+    let (config, digest) = sync::config()?;
+
+    let list = config.convert_to_typed_array("sync")?;
+
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
+
+    Ok(list)
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            id: {
+                schema: JOB_ID_SCHEMA,
+            },
+            store: {
+                schema: DATASTORE_SCHEMA,
+            },
+            remote: {
+                schema: REMOTE_ID_SCHEMA,
+            },
+            "remote-store": {
+                schema: DATASTORE_SCHEMA,
+            },
+            "remove-vanished": {
+                schema: REMOVE_VANISHED_BACKUPS_SCHEMA,
+                optional: true,
+            },
+            comment: {
+                optional: true,
+                schema: SINGLE_LINE_COMMENT_SCHEMA,
+            },
+            schedule: {
+                optional: true,
+                schema: SYNC_SCHEDULE_SCHEMA,
+            },
+        },
+    },
+)]
+/// Create a new sync job.
+pub fn create_sync_job(param: Value) -> Result<(), Error> {
+
+    let _lock = open_file_locked(sync::SYNC_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
+
+    let sync_job: sync::SyncJobConfig = serde_json::from_value(param.clone())?;
+
+    let (mut config, _digest) = sync::config()?;
+
+    if let Some(_) = config.sections.get(&sync_job.id) {
+        bail!("job '{}' already exists.", sync_job.id);
+    }
+
+    config.set_data(&sync_job.id, "sync", &sync_job)?;
+
+    sync::save_config(&config)?;
+
+    crate::config::jobstate::create_state_file("syncjob", &sync_job.id)?;
+
+    Ok(())
+}
+
+#[api(
+   input: {
+        properties: {
+            id: {
+                schema: JOB_ID_SCHEMA,
+            },
+        },
+    },
+    returns: {
+        description: "The sync job configuration.",
+        type: sync::SyncJobConfig,
+    },
+)]
+/// Read a sync job configuration.
+pub fn read_sync_job(
+    id: String,
+    mut rpcenv: &mut dyn RpcEnvironment,
+) -> Result<SyncJobConfig, Error> {
+    let (config, digest) = sync::config()?;
+
+    let sync_job = config.lookup("sync", &id)?;
+    rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
+
+    Ok(sync_job)
+}
+
+#[api()]
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all="kebab-case")]
+#[allow(non_camel_case_types)]
+/// Deletable property name
+pub enum DeletableProperty {
+    /// Delete the comment property.
+    comment,
+    /// Delete the job schedule.
+    schedule,
+    /// Delete the remove-vanished flag.
+    remove_vanished,
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            id: {
+                schema: JOB_ID_SCHEMA,
+            },
+            store: {
+                schema: DATASTORE_SCHEMA,
+                optional: true,
+            },
+            remote: {
+                schema: REMOTE_ID_SCHEMA,
+                optional: true,
+            },
+            "remote-store": {
+                schema: DATASTORE_SCHEMA,
+                optional: true,
+            },
+            "remove-vanished": {
+                schema: REMOVE_VANISHED_BACKUPS_SCHEMA,
+                optional: true,
+            },
+            comment: {
+                optional: true,
+                schema: SINGLE_LINE_COMMENT_SCHEMA,
+            },
+            schedule: {
+                optional: true,
+                schema: SYNC_SCHEDULE_SCHEMA,
+            },
+            delete: {
+                description: "List of properties to delete.",
+                type: Array,
+                optional: true,
+                items: {
+                    type: DeletableProperty,
+                }
+            },
+            digest: {
+                optional: true,
+                schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
+            },
+        },
+    },
+)]
+/// Update sync job config.
+pub fn update_sync_job(
+    id: String,
+    store: Option<String>,
+    remote: Option<String>,
+    remote_store: Option<String>,
+    remove_vanished: Option<bool>,
+    comment: Option<String>,
+    schedule: Option<String>,
+    delete: Option<Vec<DeletableProperty>>,
+    digest: Option<String>,
+) -> Result<(), Error> {
+
+    let _lock = open_file_locked(sync::SYNC_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
+
+    // pass/compare digest
+    let (mut config, expected_digest) = sync::config()?;
+
+    if let Some(ref digest) = digest {
+        let digest = proxmox::tools::hex_to_digest(digest)?;
+        crate::tools::detect_modified_configuration_file(&digest, &expected_digest)?;
+    }
+
+    let mut data: sync::SyncJobConfig = config.lookup("sync", &id)?;
+
+     if let Some(delete) = delete {
+        for delete_prop in delete {
+            match delete_prop {
+                DeletableProperty::comment => { data.comment = None; },
+                DeletableProperty::schedule => { data.schedule = None; },
+                DeletableProperty::remove_vanished => { data.remove_vanished = None; },
+            }
+        }
+    }
+
+    if let Some(comment) = comment {
+        let comment = comment.trim().to_string();
+        if comment.is_empty() {
+            data.comment = None;
+        } else {
+            data.comment = Some(comment);
+        }
+    }
+
+    if let Some(store) = store { data.store = store; }
+    if let Some(remote) = remote { data.remote = remote; }
+    if let Some(remote_store) = remote_store { data.remote_store = remote_store; }
+        
+    
+    if schedule.is_some() { data.schedule = schedule; }
+    if remove_vanished.is_some() { data.remove_vanished = remove_vanished; }
+
+    config.set_data(&id, "sync", &data)?;
+
+    sync::save_config(&config)?;
+
+    Ok(())
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            id: {
+                schema: JOB_ID_SCHEMA,
+            },
+            digest: {
+                optional: true,
+                schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
+            },
+        },
+    },
+)]
+/// Remove a sync job configuration
+pub fn delete_sync_job(id: String, digest: Option<String>) -> Result<(), Error> {
+
+    let _lock = open_file_locked(sync::SYNC_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
+
+    let (mut config, expected_digest) = sync::config()?;
+
+    if let Some(ref digest) = digest {
+        let digest = proxmox::tools::hex_to_digest(digest)?;
+        crate::tools::detect_modified_configuration_file(&digest, &expected_digest)?;
+    }
+
+    match config.sections.get(&id) {
+        Some(_) => { config.sections.remove(&id); },
+        None => bail!("job '{}' does not exist.", id),
+    }
+
+    sync::save_config(&config)?;
+
+    crate::config::jobstate::remove_state_file("syncjob", &id)?;
+
+    Ok(())
+}
+
+const ITEM_ROUTER: Router = Router::new()
+    .get(&API_METHOD_READ_SYNC_JOB)
+    .put(&API_METHOD_UPDATE_SYNC_JOB)
+    .delete(&API_METHOD_DELETE_SYNC_JOB);
+
+pub const ROUTER: Router = Router::new()
+    .get(&API_METHOD_LIST_SYNC_JOBS)
+    .post(&API_METHOD_CREATE_SYNC_JOB)
+    .match_all("id", &ITEM_ROUTER);

src/api2/helpers.rs

@@ -0,0 +1,29 @@
+use std::path::PathBuf;
+
+use anyhow::Error;
+use futures::stream::TryStreamExt;
+use hyper::{Body, Response, StatusCode, header};
+
+use proxmox::http_bail;
+
+pub async fn create_download_response(path: PathBuf) -> Result<Response<Body>, Error> {
+    let file = match tokio::fs::File::open(path.clone()).await {
+        Ok(file) => file,
+        Err(ref err) if err.kind() == std::io::ErrorKind::NotFound => {
+            http_bail!(NOT_FOUND, "open file {:?} failed - not found", path);
+        }
+        Err(err) => http_bail!(BAD_REQUEST, "open file {:?} failed: {}", path, err),
+    };
+
+    let payload = tokio_util::codec::FramedRead::new(file, tokio_util::codec::BytesCodec::new())
+        .map_ok(|bytes| hyper::body::Bytes::from(bytes.freeze()));
+
+    let body = Body::wrap_stream(payload);
+
+    // fixme: set other headers ?
+    Ok(Response::builder()
+        .status(StatusCode::OK)
+        .header(header::CONTENT_TYPE, "application/octet-stream")
+        .body(body)
+        .unwrap())
+}

src/api2/node.rs

@@ -1,24 +1,324 @@
-use proxmox::api::router::{Router, SubdirMap};
+use std::net::TcpListener;
-use proxmox::list_subdirs_api_method;
+use std::os::unix::io::AsRawFd;
 
-pub mod tasks;
+use anyhow::{bail, format_err, Error};
-mod time;
+use futures::future::{FutureExt, TryFutureExt};
-mod network;
+use hyper::body::Body;
+use hyper::http::request::Parts;
+use hyper::upgrade::Upgraded;
+use nix::fcntl::{fcntl, FcntlArg, FdFlag};
+use serde_json::{json, Value};
+use tokio::io::{AsyncBufReadExt, BufReader};
+
+use proxmox::api::router::{Router, SubdirMap};
+use proxmox::api::{
+    api, schema::*, ApiHandler, ApiMethod, ApiResponseFuture, Permission, RpcEnvironment,
+};
+use proxmox::list_subdirs_api_method;
+use proxmox::tools::websocket::WebSocket;
+use proxmox::{identity, sortable};
+
+use crate::api2::types::*;
+use crate::config::acl::PRIV_SYS_CONSOLE;
+use crate::server::WorkerTask;
+use crate::tools;
+use crate::tools::ticket::{self, Empty, Ticket};
+
+pub mod disks;
 pub mod dns;
-mod syslog;
+pub mod network;
+pub mod tasks;
+
+pub(crate) mod rrd;
+
+mod apt;
 mod journal;
 mod services;
 mod status;
+mod subscription;
+mod syslog;
+mod time;
+
+pub const SHELL_CMD_SCHEMA: Schema = StringSchema::new("The command to run.")
+    .format(&ApiStringFormat::Enum(&[
+        EnumEntry::new("login", "Login"),
+        EnumEntry::new("upgrade", "Upgrade"),
+    ]))
+    .schema();
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            cmd: {
+                schema: SHELL_CMD_SCHEMA,
+                optional: true,
+            },
+        },
+    },
+    returns: {
+        type: Object,
+        description: "Object with the user, ticket, port and upid",
+        properties: {
+            user: {
+                description: "",
+                type: String,
+            },
+            ticket: {
+                description: "",
+                type: String,
+            },
+            port: {
+                description: "",
+                type: String,
+            },
+            upid: {
+                description: "",
+                type: String,
+            },
+        }
+    },
+    access: {
+        description: "Restricted to users on realm 'pam'",
+        permission: &Permission::Privilege(&["system"], PRIV_SYS_CONSOLE, false),
+    }
+)]
+/// Call termproxy and return shell ticket
+async fn termproxy(
+    cmd: Option<String>,
+    rpcenv: &mut dyn RpcEnvironment,
+) -> Result<Value, Error> {
+    let userid: Userid = rpcenv
+        .get_user()
+        .ok_or_else(|| format_err!("unknown user"))?
+        .parse()?;
+
+    if userid.realm() != "pam" {
+        bail!("only pam users can use the console");
+    }
+
+    let path = "/system";
+
+    // use port 0 and let the kernel decide which port is free
+    let listener = TcpListener::bind("localhost:0")?;
+    let port = listener.local_addr()?.port();
+
+    let ticket = Ticket::new(ticket::TERM_PREFIX, &Empty)?
+        .sign(
+            crate::auth_helpers::private_auth_key(),
+            Some(&ticket::term_aad(&userid, &path, port)),
+        )?;
+
+    let mut command = Vec::new();
+    match cmd.as_ref().map(|x| x.as_str()) {
+        Some("login") | None => {
+            command.push("login");
+            if userid == "root@pam" {
+                command.push("-f");
+                command.push("root");
+            }
+        }
+        Some("upgrade") => {
+            if userid != "root@pam" {
+                bail!("only root@pam can upgrade");
+            }
+            // TODO: add nicer/safer wrapper like in PVE instead
+            command.push("sh");
+            command.push("-c");
+            command.push("apt full-upgrade; bash -l");
+        }
+        _ => bail!("invalid command"),
+    };
+
+    let username = userid.name().to_owned();
+    let upid = WorkerTask::spawn(
+        "termproxy",
+        None,
+        userid,
+        false,
+        move |worker| async move {
+            // move inside the worker so that it survives and does not close the port
+            // remove CLOEXEC from listenere so that we can reuse it in termproxy
+            let fd = listener.as_raw_fd();
+            let mut flags = match fcntl(fd, FcntlArg::F_GETFD) {
+                Ok(bits) => FdFlag::from_bits_truncate(bits),
+                Err(err) => bail!("could not get fd: {}", err),
+            };
+            flags.remove(FdFlag::FD_CLOEXEC);
+            if let Err(err) = fcntl(fd, FcntlArg::F_SETFD(flags)) {
+                bail!("could not set fd: {}", err);
+            }
+
+            let mut arguments: Vec<&str> = Vec::new();
+            let fd_string = fd.to_string();
+            arguments.push(&fd_string);
+            arguments.extend_from_slice(&[
+                "--path",
+                &path,
+                "--perm",
+                "Sys.Console",
+                "--authport",
+                "82",
+                "--port-as-fd",
+                "--",
+            ]);
+            arguments.extend_from_slice(&command);
+
+            let mut cmd = tokio::process::Command::new("/usr/bin/termproxy");
+
+            cmd.args(&arguments)
+                .stdout(std::process::Stdio::piped())
+                .stderr(std::process::Stdio::piped());
+
+            let mut child = cmd.spawn().expect("error executing termproxy");
+
+            let stdout = child.stdout.take().expect("no child stdout handle");
+            let stderr = child.stderr.take().expect("no child stderr handle");
+
+            let worker_stdout = worker.clone();
+            let stdout_fut = async move {
+                let mut reader = BufReader::new(stdout).lines();
+                while let Some(line) = reader.next_line().await? {
+                    worker_stdout.log(line);
+                }
+                Ok::<(), Error>(())
+            };
+
+            let worker_stderr = worker.clone();
+            let stderr_fut = async move {
+                let mut reader = BufReader::new(stderr).lines();
+                while let Some(line) = reader.next_line().await? {
+                    worker_stderr.warn(line);
+                }
+                Ok::<(), Error>(())
+            };
+
+            let mut needs_kill = false;
+            let res = tokio::select!{
+                res = &mut child => {
+                    let exit_code = res?;
+                    if !exit_code.success() {
+                        match exit_code.code() {
+                            Some(code) => bail!("termproxy exited with {}", code),
+                            None => bail!("termproxy exited by signal"),
+                        }
+                    }
+                    Ok(())
+                },
+                res = stdout_fut => res,
+                res = stderr_fut => res,
+                res = worker.abort_future() => {
+                    needs_kill = true;
+                    res.map_err(Error::from)
+                }
+            };
+
+            if needs_kill {
+                if res.is_ok() {
+                    child.kill()?;
+                    child.await?;
+                    return Ok(());
+                }
+
+                if let Err(err) = child.kill() {
+                    worker.warn(format!("error killing termproxy: {}", err));
+                } else if let Err(err) = child.await {
+                    worker.warn(format!("error awaiting termproxy: {}", err));
+                }
+            }
+
+            res
+        },
+    )?;
+
+    // FIXME: We're returning the user NAME only?
+    Ok(json!({
+        "user": username,
+        "ticket": ticket,
+        "port": port,
+        "upid": upid,
+    }))
+}
+
+#[sortable]
+pub const API_METHOD_WEBSOCKET: ApiMethod = ApiMethod::new(
+    &ApiHandler::AsyncHttp(&upgrade_to_websocket),
+    &ObjectSchema::new(
+        "Upgraded to websocket",
+        &sorted!([
+            ("node", false, &NODE_SCHEMA),
+            (
+                "vncticket",
+                false,
+                &StringSchema::new("Terminal ticket").schema()
+            ),
+            ("port", false, &IntegerSchema::new("Terminal port").schema()),
+        ]),
+    ),
+)
+.access(
+    Some("The user needs Sys.Console on /system."),
+    &Permission::Privilege(&["system"], PRIV_SYS_CONSOLE, false),
+);
+
+fn upgrade_to_websocket(
+    parts: Parts,
+    req_body: Body,
+    param: Value,
+    _info: &ApiMethod,
+    rpcenv: Box<dyn RpcEnvironment>,
+) -> ApiResponseFuture {
+    async move {
+        let userid: Userid = rpcenv.get_user().unwrap().parse()?;
+        let ticket = tools::required_string_param(&param, "vncticket")?;
+        let port: u16 = tools::required_integer_param(&param, "port")? as u16;
+
+        // will be checked again by termproxy
+        Ticket::<Empty>::parse(ticket)?
+            .verify(
+                crate::auth_helpers::public_auth_key(),
+                ticket::TERM_PREFIX,
+                Some(&ticket::term_aad(&userid, "/system", port)),
+            )?;
+
+        let (ws, response) = WebSocket::new(parts.headers)?;
+
+        crate::server::spawn_internal_task(async move {
+            let conn: Upgraded = match req_body.on_upgrade().map_err(Error::from).await {
+                Ok(upgraded) => upgraded,
+                _ => bail!("error"),
+            };
+
+            let local = tokio::net::TcpStream::connect(format!("localhost:{}", port)).await?;
+            ws.serve_connection(conn, local).await
+        });
+
+        Ok(response)
+    }
+    .boxed()
+}
 
 pub const SUBDIRS: SubdirMap = &[
+    ("apt", &apt::ROUTER),
+    ("disks", &disks::ROUTER),
     ("dns", &dns::ROUTER),
     ("journal", &journal::ROUTER),
     ("network", &network::ROUTER),
+    ("rrd", &rrd::ROUTER),
     ("services", &services::ROUTER),
     ("status", &status::ROUTER),
+    ("subscription", &subscription::ROUTER),
     ("syslog", &syslog::ROUTER),
     ("tasks", &tasks::ROUTER),
+    ("termproxy", &Router::new().post(&API_METHOD_TERMPROXY)),
     ("time", &time::ROUTER),
+    (
+        "vncwebsocket",
+        &Router::new().upgrade(&API_METHOD_WEBSOCKET),
+    ),
 ];
 
 pub const ROUTER: Router = Router::new()

src/api2/node/apt.rs

@@ -0,0 +1,268 @@
+use apt_pkg_native::Cache;
+use anyhow::{Error, bail};
+use serde_json::{json, Value};
+
+use proxmox::{list_subdirs_api_method, const_regex};
+use proxmox::api::{api, RpcEnvironment, RpcEnvironmentType, Permission};
+use proxmox::api::router::{Router, SubdirMap};
+
+use crate::server::WorkerTask;
+
+use crate::config::acl::{PRIV_SYS_AUDIT, PRIV_SYS_MODIFY};
+use crate::api2::types::{APTUpdateInfo, NODE_SCHEMA, Userid, UPID_SCHEMA};
+
+const_regex! {
+    VERSION_EPOCH_REGEX = r"^\d+:";
+    FILENAME_EXTRACT_REGEX = r"^.*/.*?_(.*)_Packages$";
+}
+
+// FIXME: Replace with call to 'apt changelog <pkg> --print-uris'. Currently
+// not possible as our packages do not have a URI set in their Release file
+fn get_changelog_url(
+    package: &str,
+    filename: &str,
+    source_pkg: &str,
+    version: &str,
+    source_version: &str,
+    origin: &str,
+    component: &str,
+) -> Result<String, Error> {
+    if origin == "" {
+        bail!("no origin available for package {}", package);
+    }
+
+    if origin == "Debian" {
+        let source_version = (VERSION_EPOCH_REGEX.regex_obj)().replace_all(source_version, "");
+
+        let prefix = if source_pkg.starts_with("lib") {
+            source_pkg.get(0..4)
+        } else {
+            source_pkg.get(0..1)
+        };
+
+        let prefix = match prefix {
+            Some(p) => p,
+            None => bail!("cannot get starting characters of package name '{}'", package)
+        };
+
+        // note: security updates seem to not always upload a changelog for
+        // their package version, so this only works *most* of the time
+        return Ok(format!("https://metadata.ftp-master.debian.org/changelogs/main/{}/{}/{}_{}_changelog",
+                          prefix, source_pkg, source_pkg, source_version));
+
+    } else if origin == "Proxmox" {
+        let version = (VERSION_EPOCH_REGEX.regex_obj)().replace_all(version, "");
+
+        let base = match (FILENAME_EXTRACT_REGEX.regex_obj)().captures(filename) {
+            Some(captures) => {
+                let base_capture = captures.get(1);
+                match base_capture {
+                    Some(base_underscore) => base_underscore.as_str().replace("_", "/"),
+                    None => bail!("incompatible filename, cannot find regex group")
+                }
+            },
+            None => bail!("incompatible filename, doesn't match regex")
+        };
+
+        return Ok(format!("http://download.proxmox.com/{}/{}_{}.changelog",
+                          base, package, version));
+    }
+
+    bail!("unknown origin ({}) or component ({})", origin, component)
+}
+
+fn list_installed_apt_packages<F: Fn(&str, &str, &str) -> bool>(filter: F)
+    -> Vec<APTUpdateInfo> {
+
+    let mut ret = Vec::new();
+
+    // note: this is not an 'apt update', it just re-reads the cache from disk
+    let mut cache = Cache::get_singleton();
+    cache.reload();
+
+    let mut cache_iter = cache.iter();
+
+    loop {
+        let view = match cache_iter.next() {
+            Some(view) => view,
+            None => break
+        };
+
+        let current_version = match view.current_version() {
+            Some(vers) => vers,
+            None => continue
+        };
+        let candidate_version = match view.candidate_version() {
+            Some(vers) => vers,
+            // if there's no candidate (i.e. no update) get info of currently
+            // installed version instead
+            None => current_version.clone()
+        };
+
+        let package = view.name();
+        if filter(&package, &current_version, &candidate_version) {
+            let mut origin_res = "unknown".to_owned();
+            let mut section_res = "unknown".to_owned();
+            let mut priority_res = "unknown".to_owned();
+            let mut change_log_url = "".to_owned();
+            let mut short_desc = package.clone();
+            let mut long_desc = "".to_owned();
+
+            // get additional information via nested APT 'iterators'
+            let mut view_iter = view.versions();
+            while let Some(ver) = view_iter.next() {
+                if ver.version() == candidate_version {
+                    if let Some(section) = ver.section() {
+                        section_res = section;
+                    }
+
+                    if let Some(prio) = ver.priority_type() {
+                        priority_res = prio;
+                    }
+
+                    // assume every package has only one origin file (not
+                    // origin, but origin *file*, for some reason those seem to
+                    // be different concepts in APT)
+                    let mut origin_iter = ver.origin_iter();
+                    let origin = origin_iter.next();
+                    if let Some(origin) = origin {
+
+                        if let Some(sd) = origin.short_desc() {
+                            short_desc = sd;
+                        }
+
+                        if let Some(ld) = origin.long_desc() {
+                            long_desc = ld;
+                        }
+
+                        // the package files appear in priority order, meaning
+                        // the one for the candidate version is first
+                        let mut pkg_iter = origin.file();
+                        let pkg_file = pkg_iter.next();
+                        if let Some(pkg_file) = pkg_file {
+                            if let Some(origin_name) = pkg_file.origin() {
+                                origin_res = origin_name;
+                            }
+
+                            let filename = pkg_file.file_name();
+                            let source_pkg = ver.source_package();
+                            let source_ver = ver.source_version();
+                            let component = pkg_file.component();
+
+                            // build changelog URL from gathered information
+                            // ignore errors, use empty changelog instead
+                            let url = get_changelog_url(&package, &filename, &source_pkg,
+                                &candidate_version, &source_ver, &origin_res, &component);
+                            if let Ok(url) = url {
+                                change_log_url = url;
+                            }
+                        }
+                    }
+
+                    break;
+                }
+            }
+
+            let info = APTUpdateInfo {
+                package,
+                title: short_desc,
+                arch: view.arch(),
+                description: long_desc,
+                change_log_url,
+                origin: origin_res,
+                version: candidate_version,
+                old_version: current_version,
+                priority: priority_res,
+                section: section_res,
+            };
+            ret.push(info);
+        }
+    }
+
+    return ret;
+}
+
+#[api(
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+        },
+    },
+    returns: {
+        description: "A list of packages with available updates.",
+        type: Array,
+        items: { type: APTUpdateInfo },
+    },
+    access: {
+        permission: &Permission::Privilege(&[], PRIV_SYS_AUDIT, false),
+    },
+)]
+/// List available APT updates
+fn apt_update_available(_param: Value) -> Result<Value, Error> {
+    let ret = list_installed_apt_packages(|_pkg, cur_ver, can_ver| cur_ver != can_ver);
+    Ok(json!(ret))
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            quiet: {
+                description: "Only produces output suitable for logging, omitting progress indicators.",
+                type: bool,
+                default: false,
+                optional: true,
+            },
+        },
+    },
+    returns: {
+        schema: UPID_SCHEMA,
+    },
+    access: {
+        permission: &Permission::Privilege(&[], PRIV_SYS_MODIFY, false),
+    },
+)]
+/// Update the APT database
+pub fn apt_update_database(
+    quiet: Option<bool>,
+    rpcenv: &mut dyn RpcEnvironment,
+) -> Result<String, Error> {
+
+    let userid: Userid = rpcenv.get_user().unwrap().parse()?;
+    let to_stdout = if rpcenv.env_type() == RpcEnvironmentType::CLI { true } else { false };
+    let quiet = quiet.unwrap_or(API_METHOD_APT_UPDATE_DATABASE_PARAM_DEFAULT_QUIET);
+
+    let upid_str = WorkerTask::new_thread("aptupdate", None, userid, to_stdout, move |worker| {
+        if !quiet { worker.log("starting apt-get update") }
+
+        // TODO: set proxy /etc/apt/apt.conf.d/76pbsproxy like PVE
+
+        let mut command = std::process::Command::new("apt-get");
+        command.arg("update");
+
+        let output = crate::tools::run_command(command, None)?;
+        if !quiet { worker.log(output) }
+
+        // TODO: add mail notify for new updates like PVE
+
+        Ok(())
+    })?;
+
+    Ok(upid_str)
+}
+
+const SUBDIRS: SubdirMap = &[
+    ("update", &Router::new()
+        .get(&API_METHOD_APT_UPDATE_AVAILABLE)
+        .post(&API_METHOD_APT_UPDATE_DATABASE)
+    ),
+];
+
+pub const ROUTER: Router = Router::new()
+    .get(&list_subdirs_api_method!(SUBDIRS))
+    .subdirs(SUBDIRS);

src/api2/node/disks.rs

@@ -0,0 +1,188 @@
+use anyhow::{bail, Error};
+use serde_json::{json, Value};
+
+use proxmox::api::{api, Permission, RpcEnvironment, RpcEnvironmentType};
+use proxmox::api::router::{Router, SubdirMap};
+use proxmox::{sortable, identity};
+use proxmox::{list_subdirs_api_method};
+
+use crate::config::acl::{PRIV_SYS_AUDIT, PRIV_SYS_MODIFY};
+use crate::tools::disks::{
+    DiskUsageInfo, DiskUsageType, DiskManage, SmartData,
+    get_disks, get_smart_data, get_disk_usage_info, inititialize_gpt_disk,
+};
+use crate::server::WorkerTask;
+
+use crate::api2::types::{Userid, UPID_SCHEMA, NODE_SCHEMA, BLOCKDEVICE_NAME_SCHEMA};
+
+pub mod directory;
+pub mod zfs;
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            skipsmart: {
+                description: "Skip smart checks.",
+                type: bool,
+                optional: true,
+                default: false,
+            },
+            "usage-type": {
+                type: DiskUsageType,
+                optional: true,
+            },
+        },
+    },
+    returns: {
+        description: "Local disk list.",
+        type: Array,
+        items: {
+            type: DiskUsageInfo,
+        },
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "disks"], PRIV_SYS_AUDIT, false),
+    },
+)]
+/// List local disks
+pub fn list_disks(
+    skipsmart: bool,
+    usage_type: Option<DiskUsageType>,
+) -> Result<Vec<DiskUsageInfo>, Error> {
+
+    let mut list = Vec::new();
+
+    for (_, info) in get_disks(None, skipsmart)? {
+        if let Some(ref usage_type) = usage_type {
+            if info.used == *usage_type {
+                list.push(info);
+            }
+        } else {
+            list.push(info);
+        }
+    }
+
+    Ok(list)
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            disk: {
+                schema: BLOCKDEVICE_NAME_SCHEMA,
+            },
+            healthonly: {
+                description: "If true returns only the health status.",
+                type: bool,
+                optional: true,
+            },
+        },
+    },
+    returns: {
+        type: SmartData,
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "disks"], PRIV_SYS_AUDIT, false),
+    },
+)]
+/// Get SMART attributes and health of a disk.
+pub fn smart_status(
+    disk: String,
+    healthonly: Option<bool>,
+) -> Result<SmartData, Error> {
+
+    let healthonly = healthonly.unwrap_or(false);
+
+    let manager = DiskManage::new();
+    let disk = manager.disk_by_name(&disk)?;
+    get_smart_data(&disk, healthonly)
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            disk: {
+                schema: BLOCKDEVICE_NAME_SCHEMA,
+            },
+            uuid: {
+                description: "UUID for the GPT table.",
+                type: String,
+                optional: true,
+                max_length: 36,
+            },
+        },
+    },
+    returns: {
+        schema: UPID_SCHEMA,
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "disks"], PRIV_SYS_MODIFY, false),
+    },
+)]
+/// Initialize empty Disk with GPT
+pub fn initialize_disk(
+    disk: String,
+    uuid: Option<String>,
+    rpcenv: &mut dyn RpcEnvironment,
+) -> Result<Value, Error> {
+
+    let to_stdout = if rpcenv.env_type() == RpcEnvironmentType::CLI { true } else { false };
+
+    let userid: Userid = rpcenv.get_user().unwrap().parse()?;
+
+    let info = get_disk_usage_info(&disk, true)?;
+
+    if info.used != DiskUsageType::Unused {
+        bail!("disk '{}' is already in use.", disk);
+    }
+
+    let upid_str = WorkerTask::new_thread(
+        "diskinit", Some(disk.clone()), userid, to_stdout, move |worker|
+        {
+            worker.log(format!("initialize disk {}", disk));
+
+            let disk_manager = DiskManage::new();
+            let disk_info = disk_manager.disk_by_name(&disk)?;
+
+            inititialize_gpt_disk(&disk_info, uuid.as_deref())?;
+
+            Ok(())
+        })?;
+
+    Ok(json!(upid_str))
+}
+
+#[sortable]
+const SUBDIRS: SubdirMap = &sorted!([
+    //    ("lvm", &lvm::ROUTER),
+    ("directory", &directory::ROUTER),
+    ("zfs", &zfs::ROUTER),
+    (
+        "initgpt", &Router::new()
+            .post(&API_METHOD_INITIALIZE_DISK)
+    ),
+    (
+        "list", &Router::new()
+            .get(&API_METHOD_LIST_DISKS)
+    ),
+    (
+        "smart", &Router::new()
+            .get(&API_METHOD_SMART_STATUS)
+    ),
+]);
+
+pub const ROUTER: Router = Router::new()
+    .get(&list_subdirs_api_method!(SUBDIRS))
+    .subdirs(SUBDIRS);

src/api2/node/disks/directory.rs

@@ -0,0 +1,282 @@
+use anyhow::{bail, Error};
+use serde_json::json;
+use ::serde::{Deserialize, Serialize};
+
+use proxmox::api::{api, Permission, RpcEnvironment, RpcEnvironmentType};
+use proxmox::api::section_config::SectionConfigData;
+use proxmox::api::router::Router;
+
+use crate::config::acl::{PRIV_SYS_AUDIT, PRIV_SYS_MODIFY};
+use crate::tools::disks::{
+    DiskManage, FileSystemType, DiskUsageType,
+    create_file_system, create_single_linux_partition, get_fs_uuid, get_disk_usage_info,
+};
+use crate::tools::systemd::{self, types::*};
+
+use crate::server::WorkerTask;
+
+use crate::api2::types::*;
+use crate::config::datastore::DataStoreConfig;
+
+#[api(
+    properties: {
+        "filesystem": {
+            type: FileSystemType,
+            optional: true,
+        },
+    },
+)]
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(rename_all="kebab-case")]
+/// Datastore mount info.
+pub struct DatastoreMountInfo {
+    /// The path of the mount unit.
+    pub unitfile: String,
+    /// The mount path.
+    pub path: String,
+    /// The mounted device.
+    pub device: String,
+    /// File system type
+    pub filesystem: Option<String>,
+    /// Mount options
+    pub options: Option<String>,
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+        }
+    },
+    returns: {
+        description: "List of systemd datastore mount units.",
+        type: Array,
+        items: {
+            type: DatastoreMountInfo,
+        },
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "disks"], PRIV_SYS_AUDIT, false),
+    },
+)]
+/// List systemd datastore mount units.
+pub fn  list_datastore_mounts() -> Result<Vec<DatastoreMountInfo>, Error> {
+
+    lazy_static::lazy_static! {
+        static ref MOUNT_NAME_REGEX: regex::Regex = regex::Regex::new(r"^mnt-datastore-(.+)\.mount$").unwrap();
+    }
+
+    let mut list = Vec::new();
+
+    let basedir = "/etc/systemd/system";
+    for item in crate::tools::fs::scan_subdir(libc::AT_FDCWD, basedir, &MOUNT_NAME_REGEX)? {
+        let item = item?;
+        let name = item.file_name().to_string_lossy().to_string();
+
+        let unitfile = format!("{}/{}", basedir, name);
+        let config = systemd::config::parse_systemd_mount(&unitfile)?;
+        let data: SystemdMountSection = config.lookup("Mount", "Mount")?;
+
+        list.push(DatastoreMountInfo {
+            unitfile,
+            device: data.What,
+            path: data.Where,
+            filesystem: data.Type,
+            options: data.Options,
+        });
+    }
+
+    Ok(list)
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            name: {
+                schema: DATASTORE_SCHEMA,
+            },
+            disk: {
+                schema: BLOCKDEVICE_NAME_SCHEMA,
+            },
+            "add-datastore": {
+                description: "Configure a datastore using the directory.",
+                type: bool,
+                optional: true,
+            },
+            filesystem: {
+                type: FileSystemType,
+                optional: true,
+            },
+         }
+    },
+    returns: {
+        schema: UPID_SCHEMA,
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "disks"], PRIV_SYS_MODIFY, false),
+    },
+)]
+/// Create a Filesystem on an unused disk. Will be mounted under '/mnt/datastore/<name>'.".
+pub fn create_datastore_disk(
+    name: String,
+    disk: String,
+    add_datastore: Option<bool>,
+    filesystem: Option<FileSystemType>,
+    rpcenv: &mut dyn RpcEnvironment,
+) -> Result<String, Error> {
+
+    let to_stdout = if rpcenv.env_type() == RpcEnvironmentType::CLI { true } else { false };
+
+    let userid: Userid = rpcenv.get_user().unwrap().parse()?;
+
+    let info = get_disk_usage_info(&disk, true)?;
+
+    if info.used != DiskUsageType::Unused {
+        bail!("disk '{}' is already in use.", disk);
+    }
+
+    let upid_str = WorkerTask::new_thread(
+        "dircreate", Some(name.clone()), userid, to_stdout, move |worker|
+        {
+            worker.log(format!("create datastore '{}' on disk {}", name, disk));
+
+            let add_datastore = add_datastore.unwrap_or(false);
+            let filesystem = filesystem.unwrap_or(FileSystemType::Ext4);
+
+            let manager = DiskManage::new();
+
+            let disk = manager.clone().disk_by_name(&disk)?;
+
+            let partition = create_single_linux_partition(&disk)?;
+            create_file_system(&partition, filesystem)?;
+
+            let uuid = get_fs_uuid(&partition)?;
+            let uuid_path = format!("/dev/disk/by-uuid/{}", uuid);
+
+            let (mount_unit_name, mount_point) = create_datastore_mount_unit(&name, filesystem, &uuid_path)?;
+
+            systemd::reload_daemon()?;
+            systemd::enable_unit(&mount_unit_name)?;
+            systemd::start_unit(&mount_unit_name)?;
+
+            if add_datastore {
+                crate::api2::config::datastore::create_datastore(json!({ "name": name, "path": mount_point }))?
+            }
+
+            Ok(())
+        })?;
+
+    Ok(upid_str)
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            name: {
+                schema: DATASTORE_SCHEMA,
+            },
+        }
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "disks"], PRIV_SYS_MODIFY, false),
+    },
+)]
+/// Remove a Filesystem mounted under '/mnt/datastore/<name>'.".
+pub fn delete_datastore_disk(name: String) -> Result<(), Error> {
+
+    let path = format!("/mnt/datastore/{}", name);
+    // path of datastore cannot be changed
+    let (config, _) = crate::config::datastore::config()?;
+    let datastores: Vec<DataStoreConfig> = config.convert_to_typed_array("datastore")?;
+    let conflicting_datastore: Option<DataStoreConfig> = datastores.into_iter()
+        .filter(|ds| ds.path == path)
+        .next();
+
+    if let Some(conflicting_datastore) = conflicting_datastore {
+        bail!("Can't remove '{}' since it's required by datastore '{}'",
+              conflicting_datastore.path, conflicting_datastore.name);
+    }
+
+    // disable systemd mount-unit
+    let mut mount_unit_name = systemd::escape_unit(&path, true);
+    mount_unit_name.push_str(".mount");
+    systemd::disable_unit(&mount_unit_name)?;
+
+    // delete .mount-file
+    let mount_unit_path = format!("/etc/systemd/system/{}", mount_unit_name);
+    let full_path = std::path::Path::new(&mount_unit_path);
+    log::info!("removing systemd mount unit {:?}", full_path);
+    std::fs::remove_file(&full_path)?;
+
+    // try to unmount, if that fails tell the user to reboot or unmount manually
+    let mut command = std::process::Command::new("umount");
+    command.arg(&path);
+    match crate::tools::run_command(command, None) {
+        Err(_) => bail!(
+            "Could not umount '{}' since it is busy. It will stay mounted \
+             until the next reboot or until unmounted manually!",
+            path
+        ),
+        Ok(_) => Ok(())
+    }
+}
+
+const ITEM_ROUTER: Router = Router::new()
+    .delete(&API_METHOD_DELETE_DATASTORE_DISK);
+
+pub const ROUTER: Router = Router::new()
+    .get(&API_METHOD_LIST_DATASTORE_MOUNTS)
+    .post(&API_METHOD_CREATE_DATASTORE_DISK)
+    .match_all("name", &ITEM_ROUTER);
+
+
+fn create_datastore_mount_unit(
+    datastore_name: &str,
+    fs_type: FileSystemType,
+    what: &str,
+) -> Result<(String, String), Error> {
+
+    let mount_point = format!("/mnt/datastore/{}", datastore_name);
+    let mut mount_unit_name = systemd::escape_unit(&mount_point, true);
+    mount_unit_name.push_str(".mount");
+
+    let mount_unit_path = format!("/etc/systemd/system/{}", mount_unit_name);
+
+    let unit = SystemdUnitSection {
+        Description: format!("Mount datatstore '{}' under '{}'", datastore_name, mount_point),
+        ..Default::default()
+    };
+
+    let install = SystemdInstallSection {
+        WantedBy: Some(vec!["multi-user.target".to_string()]),
+        ..Default::default()
+    };
+
+    let mount = SystemdMountSection {
+        What: what.to_string(),
+        Where: mount_point.clone(),
+        Type: Some(fs_type.to_string()),
+        Options: Some(String::from("defaults")),
+        ..Default::default()
+    };
+
+    let mut config = SectionConfigData::new();
+    config.set_data("Unit", "Unit", unit)?;
+    config.set_data("Install", "Install", install)?;
+    config.set_data("Mount", "Mount", mount)?;
+
+    systemd::config::save_systemd_mount(&mount_unit_path, &config)?;
+
+    Ok((mount_unit_name, mount_point))
+}

src/api2/node/disks/zfs.rs

@@ -0,0 +1,390 @@
+use anyhow::{bail, Error};
+use serde_json::{json, Value};
+use ::serde::{Deserialize, Serialize};
+
+use proxmox::api::{
+    api, Permission, RpcEnvironment, RpcEnvironmentType,
+    schema::{
+        Schema,
+        StringSchema,
+        ArraySchema,
+        IntegerSchema,
+        ApiStringFormat,
+        parse_property_string,
+    },
+};
+use proxmox::api::router::Router;
+
+use crate::config::acl::{PRIV_SYS_AUDIT, PRIV_SYS_MODIFY};
+use crate::tools::disks::{
+    zpool_list, zpool_status, parse_zpool_status_config_tree, vdev_list_to_tree,
+    DiskUsageType,
+};
+
+use crate::server::WorkerTask;
+
+use crate::api2::types::*;
+
+use crate::tools::systemd;
+
+pub const DISK_ARRAY_SCHEMA: Schema = ArraySchema::new(
+    "Disk name list.", &BLOCKDEVICE_NAME_SCHEMA)
+    .schema();
+
+pub const DISK_LIST_SCHEMA: Schema = StringSchema::new(
+    "A list of disk names, comma separated.")
+    .format(&ApiStringFormat::PropertyString(&DISK_ARRAY_SCHEMA))
+    .schema();
+
+pub const ZFS_ASHIFT_SCHEMA: Schema = IntegerSchema::new(
+    "Pool sector size exponent.")
+    .minimum(9)
+    .maximum(16)
+    .default(12)
+    .schema();
+
+pub const ZPOOL_NAME_SCHEMA: Schema =StringSchema::new("ZFS Pool Name")
+    .format(&ApiStringFormat::Pattern(&ZPOOL_NAME_REGEX))
+    .schema();
+
+#[api(
+    default: "On",
+)]
+#[derive(Debug, Copy, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+/// The ZFS compression algorithm to use.
+pub enum ZfsCompressionType {
+    /// Gnu Zip
+    Gzip,
+    /// LZ4
+    Lz4,
+    /// LZJB
+    Lzjb,
+    /// ZLE
+    Zle,
+    /// Enable compression using the default algorithm.
+    On,
+    /// Disable compression.
+    Off,
+}
+
+#[api()]
+#[derive(Debug, Copy, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+/// The ZFS RAID level to use.
+pub enum ZfsRaidLevel {
+    /// Single Disk
+    Single,
+    /// Mirror
+    Mirror,
+    /// Raid10
+    Raid10,
+    /// RaidZ
+    RaidZ,
+    /// RaidZ2
+    RaidZ2,
+    /// RaidZ3
+    RaidZ3,
+}
+
+
+#[api()]
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(rename_all="kebab-case")]
+/// zpool list item
+pub struct ZpoolListItem {
+    /// zpool name
+    pub name: String,
+    /// Health
+    pub health: String,
+    /// Total size
+    pub size: u64,
+    /// Used size
+    pub alloc: u64,
+    /// Free space
+    pub free: u64,
+    /// ZFS fragnentation level
+    pub frag: u64,
+    /// ZFS deduplication ratio
+    pub dedup: f64,
+}
+
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+        },
+    },
+    returns: {
+        description: "List of zpools.",
+        type: Array,
+        items: {
+            type: ZpoolListItem,
+        },
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "disks"], PRIV_SYS_AUDIT, false),
+    },
+)]
+/// List zfs pools.
+pub fn list_zpools() -> Result<Vec<ZpoolListItem>, Error> {
+
+    let data = zpool_list(None, false)?;
+
+    let mut list = Vec::new();
+
+    for item in data {
+        if let Some(usage) = item.usage {
+            list.push(ZpoolListItem {
+                name: item.name,
+                health: item.health,
+                size: usage.size,
+                alloc: usage.alloc,
+                free: usage.free,
+                frag: usage.frag,
+                dedup: usage.dedup,
+            });
+        }
+    }
+
+    Ok(list)
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            name: {
+                schema: ZPOOL_NAME_SCHEMA,
+            },
+        },
+    },
+    returns: {
+        description: "zpool vdev tree with status",
+        properties: {
+
+        },
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "disks"], PRIV_SYS_AUDIT, false),
+    },
+)]
+/// Get zpool status details.
+pub fn zpool_details(
+    name: String,
+) -> Result<Value, Error> {
+
+    let key_value_list = zpool_status(&name)?;
+
+    let config = match key_value_list.iter().find(|(k, _)| k == "config") {
+        Some((_, v)) => v,
+        None =>  bail!("got zpool status without config key"),
+    };
+
+    let vdev_list = parse_zpool_status_config_tree(config)?;
+    let mut tree = vdev_list_to_tree(&vdev_list)?;
+
+    for (k, v) in key_value_list {
+        if k != "config" {
+            tree[k] = v.into();
+        }
+    }
+
+    tree["name"] = tree.as_object_mut().unwrap()
+        .remove("pool")
+        .unwrap_or_else(|| name.into());
+
+
+    Ok(tree)
+}
+
+#[api(
+    protected: true,
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            name: {
+                schema: DATASTORE_SCHEMA,
+            },
+            devices: {
+                schema: DISK_LIST_SCHEMA,
+            },
+            raidlevel: {
+                type: ZfsRaidLevel,
+            },
+            ashift: {
+                schema: ZFS_ASHIFT_SCHEMA,
+                optional: true,
+            },
+            compression: {
+                type: ZfsCompressionType,
+                optional: true,
+            },
+            "add-datastore": {
+                description: "Configure a datastore using the zpool.",
+                type: bool,
+                optional: true,
+            },
+        },
+    },
+    returns: {
+        schema: UPID_SCHEMA,
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "disks"], PRIV_SYS_MODIFY, false),
+    },
+)]
+/// Create a new ZFS pool.
+pub fn create_zpool(
+    name: String,
+    devices: String,
+    raidlevel: ZfsRaidLevel,
+    compression: Option<String>,
+    ashift: Option<usize>,
+    add_datastore: Option<bool>,
+    rpcenv: &mut dyn RpcEnvironment,
+) -> Result<String, Error> {
+
+    let to_stdout = if rpcenv.env_type() == RpcEnvironmentType::CLI { true } else { false };
+
+    let userid: Userid = rpcenv.get_user().unwrap().parse()?;
+
+    let add_datastore = add_datastore.unwrap_or(false);
+
+    let ashift = ashift.unwrap_or(12);
+
+    let devices_text = devices.clone();
+    let devices = parse_property_string(&devices, &DISK_ARRAY_SCHEMA)?;
+    let devices: Vec<String> = devices.as_array().unwrap().iter()
+        .map(|v| v.as_str().unwrap().to_string()).collect();
+
+    let disk_map = crate::tools::disks::get_disks(None, true)?;
+    for disk in devices.iter() {
+        match disk_map.get(disk) {
+            Some(info) => {
+                if info.used != DiskUsageType::Unused {
+                    bail!("disk '{}' is already in use.", disk);
+                }
+            }
+            None => {
+                bail!("no such disk '{}'", disk);
+            }
+        }
+    }
+
+    let min_disks = match raidlevel {
+        ZfsRaidLevel::Single => 1,
+        ZfsRaidLevel::Mirror => 2,
+        ZfsRaidLevel::Raid10 => 4,
+        ZfsRaidLevel::RaidZ => 3,
+        ZfsRaidLevel::RaidZ2 => 4,
+        ZfsRaidLevel::RaidZ3 => 5,
+    };
+
+    // Sanity checks
+    if raidlevel == ZfsRaidLevel::Raid10 && devices.len() % 2 != 0 {
+        bail!("Raid10 needs an even number of disks.");
+    }
+
+    if raidlevel == ZfsRaidLevel::Single && devices.len() > 1 {
+        bail!("Please give only one disk for single disk mode.");
+    }
+
+    if devices.len() < min_disks {
+        bail!("{:?} needs at least {} disks.", raidlevel, min_disks);
+    }
+
+    // check if the default path does exist already and bail if it does
+    // otherwise we get an error on mounting
+    let mut default_path = std::path::PathBuf::from("/");
+    default_path.push(&name);
+
+    match std::fs::metadata(&default_path) {
+        Err(_) => {}, // path does not exist
+        Ok(_) => {
+            bail!("path {:?} already exists", default_path);
+        }
+    }
+
+     let upid_str = WorkerTask::new_thread(
+        "zfscreate", Some(name.clone()), userid, to_stdout, move |worker|
+        {
+            worker.log(format!("create {:?} zpool '{}' on devices '{}'", raidlevel, name, devices_text));
+
+
+            let mut command = std::process::Command::new("zpool");
+            command.args(&["create", "-o", &format!("ashift={}", ashift), &name]);
+
+            match raidlevel {
+                ZfsRaidLevel::Single => {
+                    command.arg(&devices[0]);
+                }
+                ZfsRaidLevel::Mirror => {
+                    command.arg("mirror");
+                    command.args(devices);
+                }
+                ZfsRaidLevel::Raid10 => {
+                     devices.chunks(2).for_each(|pair| {
+                         command.arg("mirror");
+                         command.args(pair);
+                     });
+                }
+                ZfsRaidLevel::RaidZ => {
+                    command.arg("raidz");
+                    command.args(devices);
+                }
+                ZfsRaidLevel::RaidZ2 => {
+                    command.arg("raidz2");
+                    command.args(devices);
+                }
+                ZfsRaidLevel::RaidZ3 => {
+                    command.arg("raidz3");
+                    command.args(devices);
+                }
+            }
+
+            worker.log(format!("# {:?}", command));
+
+            let output = crate::tools::run_command(command, None)?;
+            worker.log(output);
+
+            if std::path::Path::new("/lib/systemd/system/zfs-import@.service").exists() {
+                let import_unit = format!("zfs-import@{}.service", systemd::escape_unit(&name, false));
+                systemd::enable_unit(&import_unit)?;
+            }
+
+            if let Some(compression) = compression {
+                let mut command = std::process::Command::new("zfs");
+                command.args(&["set", &format!("compression={}", compression), &name]);
+                worker.log(format!("# {:?}", command));
+                let output = crate::tools::run_command(command, None)?;
+                worker.log(output);
+            }
+
+            if add_datastore {
+                let mount_point = format!("/{}", name);
+                crate::api2::config::datastore::create_datastore(json!({ "name": name, "path": mount_point }))?
+            }
+
+            Ok(())
+        })?;
+
+    Ok(upid_str)
+}
+
+pub const POOL_ROUTER: Router = Router::new()
+    .get(&API_METHOD_ZPOOL_DETAILS);
+
+pub const ROUTER: Router = Router::new()
+    .get(&API_METHOD_LIST_ZPOOLS)
+    .post(&API_METHOD_CREATE_ZPOOL)
+    .match_all("name", &POOL_ROUTER);

src/api2/node/dns.rs

@@ -1,21 +1,34 @@
 use std::sync::{Arc, Mutex};
 
-use failure::*;
+use anyhow::{Error};
 use lazy_static::lazy_static;
 use openssl::sha;
 use regex::Regex;
 use serde_json::{json, Value};
+use ::serde::{Deserialize, Serialize};
 
-use proxmox::{sortable, identity};
+use proxmox::api::{api, ApiMethod, Router, RpcEnvironment, Permission};
-use proxmox::api::{ApiHandler, ApiMethod, Router, RpcEnvironment};
-use proxmox::api::schema::*;
 use proxmox::tools::fs::{file_get_contents, replace_file, CreateOptions};
 use proxmox::{IPRE, IPV4RE, IPV6RE, IPV4OCTET, IPV6H16, IPV6LS32};
 
 use crate::api2::types::*;
+use crate::config::acl::{PRIV_SYS_AUDIT, PRIV_SYS_MODIFY};
 
 static RESOLV_CONF_FN: &str = "/etc/resolv.conf";
 
+#[api()]
+#[derive(Serialize, Deserialize)]
+#[allow(non_camel_case_types)]
+/// Deletable property name
+pub enum DeletableProperty {
+    /// Delete first nameserver entry
+    dns1,
+    /// Delete second nameserver entry
+    dns2,
+    /// Delete third nameserver entry
+    dns3,
+}
+
 pub fn read_etc_resolv_conf() -> Result<Value, Error> {
 
     let mut result = json!({});
@@ -34,6 +47,8 @@ pub fn read_etc_resolv_conf() -> Result<Value, Error> {
             concat!(r"^\s*nameserver\s+(", IPRE!(),  r")\s*")).unwrap();
     }
 
+    let mut options = String::new();
+
     for line in data.lines() {
 
         if let Some(caps) = DOMAIN_REGEX.captures(&line) {
@@ -44,16 +59,69 @@ pub fn read_etc_resolv_conf() -> Result<Value, Error> {
             let nameserver = &caps[1];
             let id = format!("dns{}", nscount);
             result[id] = Value::from(nameserver);
+        } else {
+            if !options.is_empty() { options.push('\n'); }
+            options.push_str(line);
         }
     }
 
+    if !options.is_empty() {
+        result["options"] = options.into();
+    }
+
     Ok(result)
 }
 
-fn update_dns(
+#[api(
-    param: Value,
+    protected: true,
-    _info: &ApiMethod,
+    input: {
-    _rpcenv: &mut dyn RpcEnvironment,
+        description: "Update DNS settings.",
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+            search: {
+                schema: SEARCH_DOMAIN_SCHEMA,
+                optional: true,
+            },
+            dns1: {
+                optional: true,
+                schema: FIRST_DNS_SERVER_SCHEMA,
+            },
+            dns2: {
+                optional: true,
+                schema: SECOND_DNS_SERVER_SCHEMA,
+            },
+            dns3: {
+                optional: true,
+                schema: THIRD_DNS_SERVER_SCHEMA,
+            },
+            delete: {
+                description: "List of properties to delete.",
+                type: Array,
+                optional: true,
+                items: {
+                    type: DeletableProperty,
+                }
+            },
+            digest: {
+                optional: true,
+                schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
+            },
+        },
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "network", "dns"], PRIV_SYS_MODIFY, false),
+    }
+)]
+/// Update DNS settings
+pub fn update_dns(
+    search: Option<String>,
+    dns1: Option<String>,
+    dns2: Option<String>,
+    dns3: Option<String>,
+    delete: Option<Vec<DeletableProperty>>,
+    digest: Option<String>,
 ) -> Result<Value, Error> {
 
     lazy_static! {
@@ -62,33 +130,41 @@ fn update_dns(
 
     let _guard = MUTEX.lock();
 
-    let search = crate::tools::required_string_param(&param, "search")?;
+    let mut config = read_etc_resolv_conf()?;
+    let old_digest = config["digest"].as_str().unwrap();
 
-    let raw = file_get_contents(RESOLV_CONF_FN)?;
+    if let Some(digest) = digest {
-    let old_digest = proxmox::tools::digest_to_hex(&sha::sha256(&raw));
+        crate::tools::assert_if_modified(old_digest, &digest)?;
-
-    if let Some(digest) = param["digest"].as_str() {
-        crate::tools::assert_if_modified(&old_digest, &digest)?;
     }
 
-    let old_data = String::from_utf8(raw)?;
+    if let Some(delete) = delete {
-
+        for delete_prop in delete {
-    let mut data = format!("search {}\n", search);
+            let config = config.as_object_mut().unwrap();
-
+            match delete_prop {
-    for opt in &["dns1", "dns2", "dns3"] {
+                DeletableProperty::dns1 => { config.remove("dns1"); },
-        if let Some(server) = param[opt].as_str() {
+                DeletableProperty::dns2 => { config.remove("dns2"); },
-            data.push_str(&format!("nameserver {}\n", server));
+                DeletableProperty::dns3 => { config.remove("dns3"); },
+            }
         }
     }
 
-    // append other data
+    if let Some(search) = search { config["search"] = search.into(); }
-    lazy_static! {
+    if let Some(dns1) = dns1 { config["dns1"] = dns1.into(); }
-        static ref SKIP_REGEX: Regex = Regex::new(r"^(search|domain|nameserver)\s+").unwrap();
+    if let Some(dns2) = dns2 { config["dns2"] = dns2.into(); }
+    if let Some(dns3) = dns3 { config["dns3"] = dns3.into(); }
+
+    let mut data = String::new();
+
+    if let Some(search) = config["search"].as_str() {
+        data.push_str(&format!("search {}\n", search));
     }
-    for line in old_data.lines() {
+    for opt in &["dns1", "dns2", "dns3"] {
-        if SKIP_REGEX.is_match(line) { continue; }
+        if let Some(server) = config[opt].as_str() {
-        data.push_str(line);
+            data.push_str(&format!("nameserver {}\n", server));
-        data.push('\n');
+        }
+    }
+    if let Some(options) = config["options"].as_str() {
+        data.push_str(options);
     }
 
     replace_file(RESOLV_CONF_FN, data.as_bytes(), CreateOptions::new())?;
@@ -96,7 +172,45 @@ fn update_dns(
     Ok(Value::Null)
 }
 
-fn get_dns(
+#[api(
+    input: {
+        properties: {
+            node: {
+                schema: NODE_SCHEMA,
+            },
+        },
+    },
+    returns: {
+        description: "Returns DNS server IPs and sreach domain.",
+        type: Object,
+        properties: {
+            digest: {
+                schema: PROXMOX_CONFIG_DIGEST_SCHEMA,
+            },
+            search: {
+                optional: true,
+                schema: SEARCH_DOMAIN_SCHEMA,
+            },
+            dns1: {
+                optional: true,
+                schema: FIRST_DNS_SERVER_SCHEMA,
+            },
+            dns2: {
+                optional: true,
+                schema: SECOND_DNS_SERVER_SCHEMA,
+            },
+            dns3: {
+                optional: true,
+                schema: THIRD_DNS_SERVER_SCHEMA,
+            },
+        },
+    },
+    access: {
+        permission: &Permission::Privilege(&["system", "network", "dns"], PRIV_SYS_AUDIT, false),
+    }
+)]
+/// Read DNS settings.
+pub fn get_dns(
     _param: Value,
     _info: &ApiMethod,
     _rpcenv: &mut dyn RpcEnvironment,
@@ -105,41 +219,6 @@ fn get_dns(
     read_etc_resolv_conf()
 }
 
-#[sortable]
 pub const ROUTER: Router = Router::new()
-    .get(
+    .get(&API_METHOD_GET_DNS)
-        &ApiMethod::new(
+    .put(&API_METHOD_UPDATE_DNS);
-            &ApiHandler::Sync(&get_dns),
-            &ObjectSchema::new(
-                "Read DNS settings.",
-                &sorted!([ ("node", false, &NODE_SCHEMA) ]),
-            )
-        ).returns(
-            &ObjectSchema::new(
-                "Returns DNS server IPs and sreach domain.",
-                &sorted!([
-                    ("digest", false, &PROXMOX_CONFIG_DIGEST_SCHEMA),
-                    ("search", true, &SEARCH_DOMAIN_SCHEMA),
-                    ("dns1", true, &FIRST_DNS_SERVER_SCHEMA),
-                    ("dns2", true, &SECOND_DNS_SERVER_SCHEMA),
-                    ("dns3", true, &THIRD_DNS_SERVER_SCHEMA),
-                ]),
-            ).schema()
-        )
-    )
-    .put(
-        &ApiMethod::new(
-            &ApiHandler::Sync(&update_dns),
-            &ObjectSchema::new(
-                "Returns DNS server IPs and sreach domain.",
-                &sorted!([
-                    ("node", false, &NODE_SCHEMA),
-                    ("search", false, &SEARCH_DOMAIN_SCHEMA),
-                    ("dns1", true, &FIRST_DNS_SERVER_SCHEMA),
-                    ("dns2", true, &SECOND_DNS_SERVER_SCHEMA),
-                    ("dns3", true, &THIRD_DNS_SERVER_SCHEMA),
-                    ("digest", true, &PROXMOX_CONFIG_DIGEST_SCHEMA),
-                ]),
-            )
-        ).protected(true)
-    );