bump version to 1.0.8-1

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

Cargo.toml

@@ -1,7 +1,16 @@
 [package]
 name = "proxmox-backup"
-version = "0.9.0"
+version = "1.0.8"
-authors = ["Dietmar Maurer <dietmar@proxmox.com>"]
+authors = [
+    "Dietmar Maurer <dietmar@proxmox.com>",
+    "Dominik Csapak <d.csapak@proxmox.com>",
+    "Christian Ebner <c.ebner@proxmox.com>",
+    "Fabian Grünbichler <f.gruenbichler@proxmox.com>",
+    "Stefan Reiter <s.reiter@proxmox.com>",
+    "Thomas Lamprecht <t.lamprecht@proxmox.com>",
+    "Wolfgang Bumiller <w.bumiller@proxmox.com>",
+    "Proxmox Support Team <support@proxmox.com>",
+]
 edition = "2018"
 license = "AGPL-3"
 description = "Proxmox Backup"
@@ -14,22 +23,22 @@ name = "proxmox_backup"
 path = "src/lib.rs"
 
 [dependencies]
-apt-pkg-native = "0.3.1" # custom patched version
+apt-pkg-native = "0.3.2"
 base64 = "0.12"
 bitflags = "1.2.1"
-bytes = "0.5"
+bytes = "1.0"
 crc32fast = "1"
 endian_trait = { version = "0.6", features = ["arrays"] }
 anyhow = "1.0"
 futures = "0.3"
-h2 = { version = "0.2", features = ["stream"] }
+h2 = { version = "0.3", features = [ "stream" ] }
 handlebars = "3.0"
 http = "0.2"
-hyper = "0.13.6"
+hyper = { version = "0.14", features = [ "full" ] }
 lazy_static = "1.4"
 libc = "0.2"
 log = "0.4"
-nix = "0.16"
+nix = "0.19.1"
 num-traits = "0.2"
 once_cell = "1.3.1"
 openssl = "0.10"
@@ -37,31 +46,34 @@ pam = "0.7"
 pam-sys = "0.5"
 percent-encoding = "2.1"
 pin-utils = "0.1.0"
+pin-project = "1.0"
 pathpatterns = "0.1.2"
-proxmox = { version = "0.4.2", features = [ "sortable-macro", "api-macro", "websocket" ] }
+proxmox = { version = "0.10.1", features = [ "sortable-macro", "api-macro", "websocket" ] }
-#proxmox = { git = "ssh://gitolite3@proxdev.maurer-it.com/rust/proxmox", version = "0.1.2", features = [ "sortable-macro", "api-macro" ] }
+#proxmox = { 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"
+proxmox-fuse = "0.1.1"
-pxar = { version = "0.6.1", features = [ "tokio-io", "futures-io" ] }
+pxar = { version = "0.8.0", features = [ "tokio-io" ] }
-#pxar = { path = "../pxar", features = [ "tokio-io", "futures-io" ] }
+#pxar = { path = "../pxar", features = [ "tokio-io" ] }
 regex = "1.2"
-rustyline = "6"
+rustyline = "7"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 siphasher = "0.3"
 syslog = "4.0"
-tokio = { version = "0.2.9", features = [ "blocking", "fs", "dns", "io-util", "macros", "process", "rt-threaded", "signal", "stream", "tcp", "time", "uds" ] }
+tokio = { version = "1.0", features = [ "fs", "io-util", "macros", "net", "parking_lot", "process", "rt", "rt-multi-thread", "signal", "time" ] }
-tokio-openssl = "0.4.0"
+tokio-openssl = "0.6.1"
-tokio-util = { version = "0.3", features = [ "codec" ] }
+tokio-stream = "0.1.0"
+tokio-util = { version = "0.6", features = [ "codec" ] }
 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"
+webauthn-rs = "0.2.5"
 xdg = "2.2"
 zstd = { version = "0.4", features = [ "bindgen" ] }
 nom = "5.1"
-crossbeam-channel = "0.4"
+crossbeam-channel = "0.5"
 
 [features]
 default = []

Makefile

@@ -8,8 +8,9 @@ SUBDIRS := etc www docs
 
 # Binaries usable by users
 USR_BIN := \
-	proxmox-backup-client \
+	proxmox-backup-client 	\
-	pxar
+	pxar			\
+	pmtx
 
 # Binaries usable by admins
 USR_SBIN := \
@@ -19,7 +20,8 @@ USR_SBIN := \
 SERVICE_BIN := \
 	proxmox-backup-api \
 	proxmox-backup-banner \
-	proxmox-backup-proxy
+	proxmox-backup-proxy \
+	proxmox-daily-update
 
 ifeq ($(BUILD_MODE), release)
 CARGO_BUILD_ARGS += --release
@@ -140,6 +142,8 @@ install: $(COMPILED_BINS)
 	    install -m755 $(COMPILEDIR)/$(i) $(DESTDIR)$(SBINDIR)/ ; \
 	    install -m644 zsh-completions/_$(i) $(DESTDIR)$(ZSH_COMPL_DEST)/ ;)
 	install -dm755 $(DESTDIR)$(LIBEXECDIR)/proxmox-backup
+	# install sg-tape-cmd as setuid binary
+	install -m4755 -o root -g root $(COMPILEDIR)/sg-tape-cmd $(DESTDIR)$(LIBEXECDIR)/proxmox-backup/sg-tape-cmd
 	$(foreach i,$(SERVICE_BIN), \
 	    install -m755 $(COMPILEDIR)/$(i) $(DESTDIR)$(LIBEXECDIR)/proxmox-backup/ ;)
 	$(MAKE) -C www install

README.rst

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

TODO.rst

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

debian/changelog

@@ -1,3 +1,441 @@
+rust-proxmox-backup (1.0.8-1) unstable; urgency=medium
+
+  * Https Connector: use hostname instead of URL again to avoid certificate
+    verification issues.
+
+  * ui: task summary: add verification jobs to count
+
+  * docs: explain some technical details about datastores/chunks
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 04 Feb 2021 12:39:49 +0100
+
+rust-proxmox-backup (1.0.7-1) unstable; urgency=medium
+
+  * fix #3197: skip fingerprint check when restoring key
+
+  * client: add 'import-with-master-key' command
+
+  * fix #3192: correct sort in prune sim
+
+  * tools/daemon: improve reload behaviour
+
+  * http client: add timeouts for critical connects
+
+  * api: improve error messages for restricted endpoints
+
+  * api: allow tokens to list users
+
+  * ui: running tasks: Use gettext for column labels
+
+  * login: add two-factor authenication (TFA) and integrate in web-interface
+
+  * login: support webAuthn, recovery keys and TOTP as TFA methods
+
+  * make it possible to abort tasks with CTRL-C
+
+  * fix #3245: only use default schedule for new jobs
+
+  * manager CLI: user/token list: fix rendering 0 (never) expire date
+
+  * update the event-driven, non-blocking I/O tokio platform to 1.0
+
+  * access: limit editing all pam credentials to superuser
+
+  * access: restrict password changes on @pam realm to superuser
+
+  * patch out wrongly linked libraries from ELFs to avoid extra, bogus
+    dependencies in resulting package
+
+  * add "password hint" to encryption key config
+
+  * improve GC error handling
+
+  * cli: make it possible to abort tasks with CTRL-C
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 03 Feb 2021 10:34:23 +0100
+
+rust-proxmox-backup (1.0.6-1) unstable; urgency=medium
+
+  * stricter handling of file-descriptors, fixes some cases where some could
+    leak
+
+  * ui: fix various usages of the findRecord emthod, ensuring it matches exact
+
+  * garbage collection: improve task log format
+
+  * verification: improve progress log, make it similar to what's logged on
+    pull (sync)
+
+  * datastore: move manifest locking to /run. This avoids issues with
+    filesystems which cannot natively handle removing in-use files ("delete on
+    last close"), and create a virtual, internal, replacement file to work
+    around that. This is done, for example, by NFS or CIFS (samba).
+
+ -- Proxmox Support Team <support@proxmox.com>  Fri, 11 Dec 2020 12:51:33 +0100
+
+rust-proxmox-backup (1.0.5-1) unstable; urgency=medium
+
+  * client: restore: print meta information exclusively to standard error
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 25 Nov 2020 15:29:58 +0100
+
+rust-proxmox-backup (1.0.4-1) unstable; urgency=medium
+
+  * fingerprint: add bytes() accessor
+
+  * ui: fix broken gettext use
+
+  * cli: move more commands into "snapshot" sub-command
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 25 Nov 2020 06:37:41 +0100
+
+rust-proxmox-backup (1.0.3-1) unstable; urgency=medium
+
+  * client: inform user when automatically using the default encryption key
+
+  * ui: UserView: render name as 'Firstname Lastname'
+
+  * proxmox-backup-manager: add versions command
+
+  * pxar: fix anchored exclusion at archive root
+
+  * pxar: include .pxarexclude files in the archive
+
+  * client: expose all-file-systems option
+
+  * api: make expensive parts of datastore status opt-in
+
+  * api: include datastore ID in invalid owner errors
+
+  * garbage collection: treat .bad files like regular chunks to ensure they
+    are removed if not referenced anymore
+
+  * client: fix issues with encoded UPID strings
+
+  * encryption: add fingerprint to key config
+
+  * client: add 'key show' command
+
+  * fix #3139: add key fingerprint to backup snapshot manifest and check it
+    when loading with a key
+
+  * ui: add snapshot/file fingerprint tooltip
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 24 Nov 2020 08:55:47 +0100
+
+rust-proxmox-backup (1.0.1-1) unstable; urgency=medium
+
+  * ui: datastore summary: drop 'removed bytes' display
+
+  * ui: datastore add: set default schedule
+
+  * prune sim: make backup schedule a form, bind update button to its validity
+
+  * daemon: add workaround for race in reloading and systemd 'ready' notification
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 11 Nov 2020 10:18:12 +0100
+
+rust-proxmox-backup (1.0.0-1) unstable; urgency=medium
+
+  * fix #3121: forbid removing used remotes
+
+  * docs: backup-client: encryption: discuss paperkey command
+
+  * pxar: log when skipping mount points
+
+  * ui: show also parent ACLs which affect a datastore in its panel
+
+  * api: node/apt: add versions call
+
+  * ui: make Datastore a selectable panel again. Show a datastore summary
+    list, and provide unfiltered access to all sync and verify jobs.
+
+  * ui: add help tool-button to various paneös
+
+  * ui: set various onlineHelp buttons
+
+  * zfs: mount new zpools created via API under /mnt/datastore/<id>
+
+  * ui: move disks/directory views to its own tab panel
+
+  * fix #3060: continue sync if we cannot aquire the group lock
+
+  * HttpsConnector: include destination on connect errors
+
+  * fix #3060:: improve get_owner error handling
+
+  * remote.cfg: rename userid to 'auth-id'
+
+  * verify: log/warn on invalid owner
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 10 Nov 2020 14:36:13 +0100
+
+rust-proxmox-backup (0.9.7-1) unstable; urgency=medium
+
+  * ui: add remote store selector
+
+  * tools/daemon: fix reload with open connections
+
+  * pxar/create: fix endless loop for shrinking files
+
+  * pxar/create: handle ErrorKind::Interrupted for file reads
+
+  * ui: add action-button for changing backup group owner
+
+  * docs: add interactive prune simulator
+
+  * verify: fix unprivileged verification jobs
+
+  * tasks: allow access to job tasks
+
+  * drop internal 'backup@pam' owner, sync jobs need to set a explicit owner
+
+  * api: datastore: allow to set "verify-new" option over API
+
+  * ui: datastore: add Options tab, allowing one to change per-datastore
+    notification and verify-new options
+
+  * docs: scroll navigation bar to current active section
+
+ -- Proxmox Support Team <support@proxmox.com>  Mon, 09 Nov 2020 07:36:58 +0100
+
+rust-proxmox-backup (0.9.6-1) unstable; urgency=medium
+
+  * fix #3106: improve queueing new incoming connections
+
+  * fix #2870: sync: ensure a updated ticket is used, if available
+
+  * proxy: log if there are too many open connections
+
+  * ui: SyncJobEdit: fix sending 'delete' values on SyncJob creation
+
+  * datastore config: allow to configure who receives job notify emails
+
+  * ui: fix task description for log rotate
+
+  * proxy: also rotate auth.log file
+
+  * ui: add shell panel under administration
+
+  * ui: sync jobs: only set default schedule when creating new jobs and some
+    other small fixes
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 04 Nov 2020 19:12:57 +0100
+
+rust-proxmox-backup (0.9.5-1) unstable; urgency=medium
+
+  * ui: user menu: allow one to change the language while staying logged in
+
+  * proxmox-backup-manager: add subscription commands
+
+  * server/rest: also accept = as token separator
+
+  * privs: allow reading snapshot notes with Datastore.Audit
+
+  * privs: enforce Datastore.Modify|Backup to set backup notes
+
+  * verify: introduce and use new Datastore.Verify privilege
+
+  * docs: add API tokens to documentation
+
+  * ui: various smaller layout and icon improvements
+
+  * api: implement apt pkg cache for caching pending updates
+
+  * api: apt: implement support to send notification email on new updates
+
+  * add daily update and maintenance task
+
+  * fix #2864: add owner option to sync
+
+  * sync: allow sync for non-superusers under special conditions
+
+  * config: support depreacated netmask when parsing interfaces file
+
+  * server: implement access log rotation with re-open via command socket
+
+  * garbage collect: improve index error messages
+
+  * fix #3039: use the same ID regex for info and api
+
+  * ui: administration: allow extensive filtering of the worker task
+
+  * report: add api endpoint and function to generate report
+
+ -- Proxmox Support Team <support@proxmox.com>  Tue, 03 Nov 2020 17:41:17 +0100
+
+rust-proxmox-backup (0.9.4-2) unstable; urgency=medium
+
+  * make postinst (update) script more resilient
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 29 Oct 2020 20:09:30 +0100
+
+rust-proxmox-backup (0.9.4-1) unstable; urgency=medium
+
+  * implement API-token
+
+  * client/remote: allow using API-token + secret
+
+  * ui/cli: implement API-token management interface and commands
+
+  * ui: add widget to view the effective permissions of a user or token
+
+  * ui: datastore summary: handle error when havin zero snapshot of any type
+
+  * ui: move user, token and permissions into an access control tab panel
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 29 Oct 2020 17:19:13 +0100
+
+rust-proxmox-backup (0.9.3-1) unstable; urgency=medium
+
+  * fix #2998: encode mtime as i64 instead of u64
+
+  * GC: log the number of leftover bad chunks we could not yet cleanup, as no
+    valid one replaced them. Also log deduplication factor.
+
+  * send sync job status emails
+
+  * api: datstore status: introduce proper structs and restore compatibility
+    to 0.9.1
+
+  * ui: drop id field from verify/sync add window, they are now seen as internal
+
+ -- Proxmox Support Team <support@proxmox.com>  Thu, 29 Oct 2020 14:58:13 +0100
+
+rust-proxmox-backup (0.9.2-2) unstable; urgency=medium
+
+  * rework server web-interface, move more datastore related panels as tabs
+    inside the datastore view
+
+  * prune: never fail, just warn about failed removals
+
+  * prune/forget: skip snapshots with open readers (restore, verification)
+
+  * datastore: always ensure to remove individual snapshots before their group
+
+  * pxar: fix relative '!' rules in .pxarexclude
+
+  * pxar: anchor pxarexcludes starting with a slash
+
+  * GC: mark phase: ignore vanished index files
+
+  * server/rest: forward real client IP on proxied request and log it in
+    failed authentication requests
+
+  * server: rest: implement max URI path and query length request limits
+
+  * server/rest: implement request access log and log the query part of
+    URL and the user agent
+
+  * api: access: log to separate file, use syslog to errors only to reduce
+    syslog spam
+
+  * client: set HTTP connect timeout to 10 seconds
+
+  * client: sent TCP keep-alive after 2 minutes instead of the Linux default
+    of two hours.
+
+  * CLI completion: fix ACL path completion
+
+  * fix #2988: allow one to enable automatic verification after finishing a
+    snapshot, can be controlled as a per-datastore option
+
+  * various log-rotation improvements
+
+  * proxmox-backup-client: use HumanByte to render snapshot size
+
+  * paperkey: use svg as image format to provide better scalability
+
+  * backup: avoid Transport endpoint is not connected error
+
+  * fix #3038: check user before renewing ticket
+
+  * ui/tools: add zip module and allow to download an archive directory as a zip
+
+  * ui and api: add verification job config, allowing to schedule more
+    flexible jobs, filtering out already and/or recently verified snapshots
+    NOTE: the previous simple "verify all" schedule was dropped from the
+    datastore content, and does *not* gets migrated to the new job config.
+
+  * tasks: use systemd escape to decode/encode the task worker ID, avoiding
+    some display problems with problematic characters
+
+  * fix #2934: list also new to-be-installed packages in updates
+
+  * apt: add /changelog API call similar to PVE
+
+  * api: add world accessible ping dummy endpoint, to cheaply check for a
+    running PBS instance.
+
+  * ui: add datastore summary panel and move Statistics into it
+
+  * ui: navigation: add 'Add Datastore' button below datastore list
+
+  * ui: datastore panel: save and restore selected tab statefully
+
+  * send notification mails to email of root@pam account for GC and verify
+    jobs
+
+  * ui: datastore: use simple V. for verify action button
+
+  * ui: datastore: show snapshot manifest comment and allow to edit them
+
+ -- Proxmox Support Team <support@proxmox.com>  Wed, 28 Oct 2020 23:05:41 +0100
+
+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 download 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: implement 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

debian/control

@@ -7,24 +7,25 @@ Build-Depends: debhelper (>= 11),
  rustc:native,
  libstd-rust-dev,
  librust-anyhow-1+default-dev,
- librust-apt-pkg-native-0.3+default-dev (>= 0.3.1-~~),
+ librust-apt-pkg-native-0.3+default-dev (>= 0.3.2-~~),
  librust-base64-0.12+default-dev,
  librust-bitflags-1+default-dev (>= 1.2.1-~~),
- librust-bytes-0.5+default-dev,
+ librust-bytes-1+default-dev,
  librust-crc32fast-1+default-dev,
- librust-crossbeam-channel-0.4+default-dev,
+ librust-crossbeam-channel-0.5+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.3+default-dev,
- librust-h2-0.2+stream-dev,
+ librust-h2-0.3+stream-dev,
  librust-handlebars-3+default-dev,
  librust-http-0.2+default-dev,
- librust-hyper-0.13+default-dev (>= 0.13.6-~~),
+ librust-hyper-0.14+default-dev,
+ librust-hyper-0.14+full-dev,
  librust-lazy-static-1+default-dev (>= 1.4-~~),
  librust-libc-0.2+default-dev,
  librust-log-0.4+default-dev,
- librust-nix-0.16+default-dev,
+ librust-nix-0.19+default-dev (>= 0.19.1-~~),
  librust-nom-5+default-dev (>= 5.1-~~),
  librust-num-traits-0.2+default-dev,
  librust-once-cell-1+default-dev (>= 1.3.1-~~),
@@ -33,42 +34,42 @@ Build-Depends: debhelper (>= 11),
  librust-pam-sys-0.5+default-dev,
  librust-pathpatterns-0.1+default-dev (>= 0.1.2-~~),
  librust-percent-encoding-2+default-dev (>= 2.1-~~),
+ librust-pin-project-1+default-dev,
  librust-pin-utils-0.1+default-dev,
- librust-proxmox-0.4+api-macro-dev (>= 0.4.2-~~),
+ librust-proxmox-0.10+api-macro-dev (>= 0.10.1-~~),
- librust-proxmox-0.4+default-dev (>= 0.4.2-~~),
+ librust-proxmox-0.10+default-dev (>= 0.10.1-~~),
- librust-proxmox-0.4+sortable-macro-dev (>= 0.4.2-~~),
+ librust-proxmox-0.10+sortable-macro-dev (>= 0.10.1-~~),
- librust-proxmox-0.4+websocket-dev (>= 0.4.2-~~),
+ librust-proxmox-0.10+websocket-dev (>= 0.10.1-~~),
- librust-proxmox-fuse-0.1+default-dev,
+ librust-proxmox-fuse-0.1+default-dev (>= 0.1.1-~~),
- librust-pxar-0.6+default-dev (>= 0.6.1-~~),
+ librust-pxar-0.8+default-dev,
- librust-pxar-0.6+futures-io-dev (>= 0.6.1-~~),
+ librust-pxar-0.8+tokio-io-dev,
- librust-pxar-0.6+tokio-io-dev (>= 0.6.1-~~),
  librust-regex-1+default-dev (>= 1.2-~~),
- librust-rustyline-6+default-dev,
+ librust-rustyline-7+default-dev,
  librust-serde-1+default-dev,
  librust-serde-1+derive-dev,
  librust-serde-json-1+default-dev,
  librust-siphasher-0.3+default-dev,
  librust-syslog-4+default-dev,
- librust-tokio-0.2+blocking-dev (>= 0.2.9-~~),
+ librust-tokio-1+default-dev,
- librust-tokio-0.2+default-dev (>= 0.2.9-~~),
+ librust-tokio-1+fs-dev,
- librust-tokio-0.2+dns-dev (>= 0.2.9-~~),
+ librust-tokio-1+io-util-dev,
- librust-tokio-0.2+fs-dev (>= 0.2.9-~~),
+ librust-tokio-1+macros-dev,
- librust-tokio-0.2+io-util-dev (>= 0.2.9-~~),
+ librust-tokio-1+net-dev,
- librust-tokio-0.2+macros-dev (>= 0.2.9-~~),
+ librust-tokio-1+parking-lot-dev,
- librust-tokio-0.2+process-dev (>= 0.2.9-~~),
+ librust-tokio-1+process-dev,
- librust-tokio-0.2+rt-threaded-dev (>= 0.2.9-~~),
+ librust-tokio-1+rt-dev,
- librust-tokio-0.2+signal-dev (>= 0.2.9-~~),
+ librust-tokio-1+rt-multi-thread-dev,
- librust-tokio-0.2+stream-dev (>= 0.2.9-~~),
+ librust-tokio-1+signal-dev,
- librust-tokio-0.2+tcp-dev (>= 0.2.9-~~),
+ librust-tokio-1+time-dev,
- librust-tokio-0.2+time-dev (>= 0.2.9-~~),
+ librust-tokio-openssl-0.6+default-dev (>= 0.6.1-~~),
- librust-tokio-0.2+uds-dev (>= 0.2.9-~~),
+ librust-tokio-stream-0.1+default-dev,
- librust-tokio-openssl-0.4+default-dev,
+ librust-tokio-util-0.6+codec-dev,
- librust-tokio-util-0.3+codec-dev,
+ librust-tokio-util-0.6+default-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-webauthn-rs-0.2+default-dev (>= 0.2.5-~~),
  librust-xdg-2+default-dev (>= 2.2-~~),
  librust-zstd-0.4+bindgen-dev,
  librust-zstd-0.4+default-dev,
@@ -76,50 +77,62 @@ Build-Depends: debhelper (>= 11),
  libfuse3-dev,
  libsystemd-dev,
  uuid-dev,
- debhelper (>= 12~),
+ libsgutils2-dev,
  bash-completion,
- pve-eslint,
+ debhelper (>= 12~),
- python3-docutils,
- python3-pygments,
- rsync,
  fonts-dejavu-core <!nodoc>,
  fonts-lato <!nodoc>,
  fonts-open-sans <!nodoc>,
  graphviz <!nodoc>,
  latexmk <!nodoc>,
+ patchelf,
+ pve-eslint (>= 7.18.0-1),
+ python3-docutils,
+ python3-pygments,
  python3-sphinx <!nodoc>,
+ rsync,
  texlive-fonts-extra <!nodoc>,
  texlive-fonts-recommended <!nodoc>,
  texlive-xetex <!nodoc>,
  xindy <!nodoc>
 Maintainer: Proxmox Support Team <support@proxmox.com>
 Standards-Version: 4.4.1
-Vcs-Git: 
+Vcs-Git: git://git.proxmox.com/git/proxmox-backup.git
-Vcs-Browser: 
+Vcs-Browser: https://git.proxmox.com/?p=proxmox-backup.git;a=summary
 Homepage: https://www.proxmox.com
 
 Package: proxmox-backup-server
 Architecture: any
 Depends: fonts-font-awesome,
          libjs-extjs (>= 6.0.1),
+         libjs-qrcodejs (>= 1.20201119),
+         libsgutils2-2,
          libzstd1 (>= 1.3.8),
          lvm2,
+         mt-st,
+         mtx,
+         openssh-server,
          pbs-i18n,
+         postfix | mail-transport-agent,
          proxmox-backup-docs,
          proxmox-mini-journalreader,
-         proxmox-widget-toolkit (>= 2.2-4),
+         proxmox-widget-toolkit (>= 2.3-6),
          pve-xtermjs (>= 4.7.0-1),
+         sg3-utils,
          smartmontools,
          ${misc:Depends},
          ${shlibs:Depends},
 Recommends: zfsutils-linux,
+            ifupdown2,
 Description: Proxmox Backup Server daemon with tools and GUI
  This package contains the Proxmox Backup Server daemons and related
  tools. This includes a web-based graphical user interface.
 
 Package: proxmox-backup-client
 Architecture: any
-Depends: qrencode ${misc:Depends}, ${shlibs:Depends}
+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/control.in

@@ -2,24 +2,34 @@ Package: proxmox-backup-server
 Architecture: any
 Depends: fonts-font-awesome,
          libjs-extjs (>= 6.0.1),
+         libjs-qrcodejs (>= 1.20201119),
+         libsgutils2-2,
          libzstd1 (>= 1.3.8),
          lvm2,
+         mt-st,
+         mtx,
+         openssh-server,
          pbs-i18n,
+         postfix | mail-transport-agent,
          proxmox-backup-docs,
          proxmox-mini-journalreader,
-         proxmox-widget-toolkit (>= 2.3-1),
+         proxmox-widget-toolkit (>= 2.3-6),
          pve-xtermjs (>= 4.7.0-1),
+         sg3-utils,
          smartmontools,
          ${misc:Depends},
          ${shlibs:Depends},
 Recommends: zfsutils-linux,
+            ifupdown2,
 Description: Proxmox Backup Server daemon with tools and GUI
  This package contains the Proxmox Backup Server daemons and related
  tools. This includes a web-based graphical user interface.
 
 Package: proxmox-backup-client
 Architecture: any
-Depends: qrencode ${misc:Depends}, ${shlibs:Depends}
+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/copyright

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

debian/debcargo.toml

@@ -2,33 +2,32 @@ overlay = "."
 crate_src_path = ".."
 whitelist = ["tests/*.c"]
 
-# needed for pinutils alpha
+maintainer = "Proxmox Support Team <support@proxmox.com>"
-allow_prerelease_deps = true
 
 [source]
-# TODO: update once public
+vcs_git = "git://git.proxmox.com/git/proxmox-backup.git"
-vcs_git = ""
+vcs_browser = "https://git.proxmox.com/?p=proxmox-backup.git;a=summary"
-vcs_browser = ""
-maintainer = "Proxmox Support Team <support@proxmox.com>"
 section = "admin"
 build_depends = [
-  "debhelper (>= 12~)",
   "bash-completion",
-  "pve-eslint",
+  "debhelper (>= 12~)",
-  "python3-docutils",
-  "python3-pygments",
-  "rsync",
   "fonts-dejavu-core <!nodoc>",
   "fonts-lato <!nodoc>",
   "fonts-open-sans <!nodoc>",
   "graphviz <!nodoc>",
   "latexmk <!nodoc>",
+  "patchelf",
+  "pve-eslint (>= 7.18.0-1)",
+  "python3-docutils",
+  "python3-pygments",
   "python3-sphinx <!nodoc>",
+  "rsync",
   "texlive-fonts-extra <!nodoc>",
   "texlive-fonts-recommended <!nodoc>",
   "texlive-xetex <!nodoc>",
   "xindy <!nodoc>",
 ]
+
 build_depends_excludes = [
   "debhelper (>=11)",
 ]
@@ -39,4 +38,5 @@ depends = [
   "libfuse3-dev",
   "libsystemd-dev",
   "uuid-dev",
+  "libsgutils2-dev",
 ]

debian/lintian-overrides

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

debian/pmtx.bc

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

debian/postinst

@@ -6,6 +6,9 @@ set -e
 
 case "$1" in
     configure)
+	# need to have user backup in the tapoe group
+	usermod -a -G tape backup
+
 	# modeled after dh_systemd_start output
 	systemctl --system daemon-reload >/dev/null || true
 	if [ -n "$2" ]; then
@@ -15,10 +18,33 @@ case "$1" in
 	fi
 	deb-systemd-invoke $_dh_action proxmox-backup.service proxmox-backup-proxy.service >/dev/null || true
 
+	# FIXME: Remove with 1.1
+	if test -n "$2"; then
+		if dpkg --compare-versions "$2" 'lt' '0.9.4-1'; then
+			if grep -s -q  -P -e '^\s+verify-schedule ' /etc/proxmox-backup/datastore.cfg; then
+				echo "NOTE: drop all verify schedules from datastore config."
+				echo "You can now add more flexible verify jobs"
+				flock -w 30 /etc/proxmox-backup/.datastore.lck \
+				    sed -i '/^\s\+verify-schedule /d' /etc/proxmox-backup/datastore.cfg || true
+			fi
+		fi
+		if dpkg --compare-versions "$2" 'le' '0.9.5-1'; then
+			chown --quiet backup:backup /var/log/proxmox-backup/api/auth.log || true
+		fi
+		if dpkg --compare-versions "$2" 'le' '0.9.7-1'; then
+			if [ -e /etc/proxmox-backup/remote.cfg ]; then
+				echo "NOTE: Switching over remote.cfg to new field names.."
+				flock -w 30 /etc/proxmox-backup/.remote.lck \
+				    sed -i \
+				        -e 's/^\s\+userid /\tauth-id /g' \
+				        /etc/proxmox-backup/remote.cfg || true
+			fi
+		fi
+	fi
 	# FIXME: Remove in future version once we're sure no broken entries remain in anyone's files
 	if grep -q -e ':termproxy::[^@]\+: ' /var/log/proxmox-backup/tasks/active; then
 	    echo "Fixing up termproxy user id in task log..."
-	    flock -w 30 /var/log/proxmox-backup/tasks/active.lock sed -i 's/:termproxy::\([^@]\+\): /:termproxy::\1@pam: /' /var/log/proxmox-backup/tasks/active
+	    flock -w 30 /var/log/proxmox-backup/tasks/active.lock sed -i 's/:termproxy::\([^@]\+\): /:termproxy::\1@pam: /' /var/log/proxmox-backup/tasks/active || true
 	fi
     ;;
 

debian/prerm

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

debian/proxmox-backup-docs.links

@@ -1 +1,3 @@
 /usr/share/doc/proxmox-backup/proxmox-backup.pdf /usr/share/doc/proxmox-backup/html/proxmox-backup.pdf
+/usr/share/javascript/extjs /usr/share/doc/proxmox-backup/html/prune-simulator/extjs
+/usr/share/javascript/extjs /usr/share/doc/proxmox-backup/html/lto-barcode/extjs

debian/proxmox-backup-server.bash-completion

@@ -1 +1,2 @@
 debian/proxmox-backup-manager.bc proxmox-backup-manager
+debian/pmtx.bc pmtx

debian/proxmox-backup-server.install

@@ -1,16 +1,22 @@
 etc/proxmox-backup-proxy.service /lib/systemd/system/
 etc/proxmox-backup.service /lib/systemd/system/
 etc/proxmox-backup-banner.service /lib/systemd/system/
-etc/pbstest-beta.list /etc/apt/sources.list.d/
+etc/proxmox-backup-daily-update.service /lib/systemd/system/
+etc/proxmox-backup-daily-update.timer /lib/systemd/system/
+etc/pbs-enterprise.list /etc/apt/sources.list.d/
 usr/lib/x86_64-linux-gnu/proxmox-backup/proxmox-backup-api
 usr/lib/x86_64-linux-gnu/proxmox-backup/proxmox-backup-proxy
 usr/lib/x86_64-linux-gnu/proxmox-backup/proxmox-backup-banner
+usr/lib/x86_64-linux-gnu/proxmox-backup/proxmox-daily-update
+usr/lib/x86_64-linux-gnu/proxmox-backup/sg-tape-cmd
 usr/sbin/proxmox-backup-manager
+usr/bin/pmtx
 usr/share/javascript/proxmox-backup/index.hbs
 usr/share/javascript/proxmox-backup/css/ext6-pbs.css
-usr/share/javascript/proxmox-backup/images/logo-128.png
+usr/share/javascript/proxmox-backup/images
-usr/share/javascript/proxmox-backup/images/proxmox_logo.png
 usr/share/javascript/proxmox-backup/js/proxmox-backup-gui.js
 usr/share/man/man1/proxmox-backup-manager.1
 usr/share/man/man1/proxmox-backup-proxy.1
+usr/share/man/man1/pmtx.1
 usr/share/zsh/vendor-completions/_proxmox-backup-manager
+usr/share/zsh/vendor-completions/_pmtx

debian/proxmox-backup-server.maintscript

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

debian/rules

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

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

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

docs/Makefile

@@ -5,15 +5,35 @@ GENERATED_SYNOPSIS := 						\
 	proxmox-backup-client/catalog-shell-synopsis.rst 	\
 	proxmox-backup-manager/synopsis.rst			\
 	pxar/synopsis.rst					\
+	pmtx/synopsis.rst					\
 	backup-protocol-api.rst					\
 	reader-protocol-api.rst
 
 MANUAL_PAGES := 			\
 	pxar.1				\
+	pmtx.1				\
 	proxmox-backup-proxy.1		\
 	proxmox-backup-client.1		\
 	proxmox-backup-manager.1
 
+PRUNE_SIMULATOR_FILES := 					\
+	prune-simulator/index.html				\
+	prune-simulator/documentation.html			\
+	prune-simulator/clear-trigger.png			\
+	prune-simulator/prune-simulator.js
+
+LTO_BARCODE_FILES :=						\
+	lto-barcode/index.html					\
+	lto-barcode/code39.js					\
+	lto-barcode/prefix-field.js				\
+	lto-barcode/label-style.js				\
+	lto-barcode/tape-type.js				\
+	lto-barcode/paper-size.js				\
+	lto-barcode/page-layout.js				\
+	lto-barcode/page-calibration.js				\
+	lto-barcode/label-list.js				\
+	lto-barcode/label-setup.js				\
+	lto-barcode/lto-barcode.js
 
 # Sphinx documentation setup
 SPHINXOPTS    =
@@ -49,6 +69,14 @@ pxar/synopsis.rst: ${COMPILEDIR}/pxar
 pxar.1: pxar/man1.rst  pxar/description.rst pxar/synopsis.rst
 	rst2man $< >$@
 
+
+pmtx/synopsis.rst: ${COMPILEDIR}/pmtx
+	${COMPILEDIR}/pmtx printdoc > pmtx/synopsis.rst
+
+pmtx.1: pmtx/man1.rst  pmtx/description.rst pmtx/synopsis.rst
+	rst2man $< >$@
+
+
 proxmox-backup-client/synopsis.rst: ${COMPILEDIR}/proxmox-backup-client
 	${COMPILEDIR}/proxmox-backup-client printdoc > proxmox-backup-client/synopsis.rst
 
@@ -74,10 +102,13 @@ onlinehelpinfo:
 	@echo "Build finished. OnlineHelpInfo.js is in $(BUILDDIR)/scanrefs."
 
 .PHONY: html
-html: ${GENERATED_SYNOPSIS} images/proxmox-logo.svg custom.css conf.py
+html: ${GENERATED_SYNOPSIS} images/proxmox-logo.svg custom.css conf.py ${PRUNE_SIMULATOR_FILES} ${LTO_BARCODE_FILES}
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	cp images/proxmox-logo.svg $(BUILDDIR)/html/_static/
+	install -m 0644 custom.js custom.css images/proxmox-logo.svg $(BUILDDIR)/html/_static/
-	cp custom.css $(BUILDDIR)/html/_static/
+	install -dm 0755 $(BUILDDIR)/html/prune-simulator
+	install -m 0644 ${PRUNE_SIMULATOR_FILES} $(BUILDDIR)/html/prune-simulator
+	install -dm 0755 $(BUILDDIR)/html/lto-barcode
+	install -m 0644 ${LTO_BARCODE_FILES} $(BUILDDIR)/html/lto-barcode
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

docs/_ext/proxmox-scanrefs.py

@@ -44,12 +44,13 @@ def scan_extjs_files(wwwdir="../www"): # a bit rough i know, but we can optimize
                 js_files.append(os.path.join(root, filename))
     for js_file in js_files:
         fd = open(js_file).read()
-        match = re.search("onlineHelp:\s*[\'\"](.*?)[\'\"]", fd) # match object is tuple
+        allmatch = re.findall("(?:onlineHelp:|get_help_tool\s*\()\s*[\'\"](.*?)[\'\"]", fd, re.M)
-        if match:
+        for match in allmatch:
-            anchor = match.groups()[0]
+            anchor = match
             anchor = re.sub('_', '-', anchor) # normalize labels
             logger.info("found onlineHelp: {} in {}".format(anchor, js_file))
             used_anchors.append(anchor)
+
     return used_anchors
 
 
@@ -72,7 +73,9 @@ class ReflabelMapper(Builder):
             'link': '/docs/index.html',
             'title': 'Proxmox Backup Server Documentation Index',
         }
-        self.env.used_anchors = scan_extjs_files()
+        # Disabled until we find a sensible way to scan proxmox-widget-toolkit
+        # as well
+        #self.env.used_anchors = scan_extjs_files()
 
         if not os.path.isdir(self.outdir):
             os.mkdir(self.outdir)
@@ -92,6 +95,9 @@ class ReflabelMapper(Builder):
                     logger.info('traversing section {}'.format(title.astext()))
                     ref_name = getattr(title, 'rawsource', title.astext())
 
+                    if (ref_name[:7] == ':term:`'):
+                        ref_name = ref_name[7:-1]
+
                     self.env.online_help[labelid] = {'link': '', 'title': ''}
                     self.env.online_help[labelid]['link'] = "/docs/" + os.path.basename(filename_html) + "#{}".format(labelid)
                     self.env.online_help[labelid]['title'] = ref_name
@@ -111,15 +117,18 @@ class ReflabelMapper(Builder):
     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:
+        # Disabled until we find a sensible way to scan proxmox-widget-toolkit
-                logger.info("[-] anchor {} is missing from onlinehelp!".format(anchor))
+        # as well
-        for anchor in self.env.online_help:
+        #for anchor in self.env.used_anchors:
-            if anchor not in self.env.used_anchors and anchor != 'pbs_documentation_index':
+        #    if anchor not in self.env.online_help:
-                logger.info("[*] anchor {} not used! deleting...".format(anchor))
+        #        logger.info("[-] anchor {} is missing from onlinehelp!".format(anchor))
-                to_remove.append(anchor)
+        #for anchor in self.env.online_help:
-        for anchor in to_remove:
+        #    if anchor not in self.env.used_anchors and anchor != 'pbs_documentation_index':
-            self.env.online_help.pop(anchor, None)
+        #        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):

docs/backup-client.rst

@@ -0,0 +1,752 @@
+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 (for example, `[fe80::01]`).
+
+You can pass the repository with the ``--repository`` command line option, or
+by setting the ``PBS_REPOSITORY`` environment variable.
+
+Here some examples of valid repositories and the real values
+
+================================ ================== ================== ===========
+Example                          User               Host:Port          Datastore
+================================ ================== ================== ===========
+mydatastore                      ``root@pam``       localhost:8007     mydatastore
+myhostname:mydatastore           ``root@pam``       myhostname:8007    mydatastore
+user@pbs@myhostname:mydatastore  ``user@pbs``       myhostname:8007    mydatastore
+user\@pbs!token@host:store       ``user@pbs!token`` myhostname:8007    mydatastore
+192.168.55.55:1234:mydatastore   ``root@pam``       192.168.55.55:1234 mydatastore
+[ff80::51]:mydatastore           ``root@pam``       [ff80::51]:8007    mydatastore
+[ff80::51]:1234:mydatastore      ``root@pam``       [ff80::51]:1234    mydatastore
+================================ ================== ================== ===========
+
+Environment Variables
+---------------------
+
+``PBS_REPOSITORY``
+  The default backup repository.
+
+``PBS_PASSWORD``
+  When set, this value is used for the password required for the backup server.
+  You can also set this to a API token secret.
+
+``PBS_ENCRYPTION_PASSWORD``
+  When set, this value is used to access the secret encryption key (if
+  protected by password).
+
+``PBS_FINGERPRINT`` When set, this value is used to verify the server
+  certificate (only used if the system CA certificates cannot 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:
+
+Encryption
+----------
+
+Proxmox Backup supports client-side encryption with AES-256 in GCM_
+mode. To set this up, you first need to create an encryption key:
+
+.. code-block:: console
+
+  # proxmox-backup-client key create my-backup.key
+  Encryption Key Password: **************
+
+The key is password protected by default. If you do not need this
+extra protection, you can also create it without a password:
+
+.. code-block:: console
+
+  # proxmox-backup-client key create /path/to/my-backup.key --kdf none
+
+Having created this key, it is now possible to create an encrypted backup, by
+passing the ``--keyfile`` parameter, with the path to the key file.
+
+.. code-block:: console
+
+  # proxmox-backup-client backup etc.pxar:/etc --keyfile /path/to/my-backup.key
+  Password: *********
+  Encryption Key Password: **************
+  ...
+
+.. Note:: If you do not specify the name of the backup key, the key will be
+  created in the default location
+  ``~/.config/proxmox-backup/encryption-key.json``. ``proxmox-backup-client``
+  will also search this location by default, in case the ``--keyfile``
+  parameter is not specified.
+
+You can avoid entering the passwords by setting the environment
+variables ``PBS_PASSWORD`` and ``PBS_ENCRYPTION_PASSWORD``.
+
+
+Using a master key to store and recover encryption keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also use ``proxmox-backup-client key`` to create an RSA public/private
+key pair, which can be used to store an encrypted version of the symmetric
+backup encryption key alongside each backup and recover it later.
+
+To set up a master key:
+
+1. Create an encryption key for the backup:
+
+   .. code-block:: console
+
+     # proxmox-backup-client key create
+     creating default key at: "~/.config/proxmox-backup/encryption-key.json"
+     Encryption Key Password: **********
+     ...
+
+   The resulting file will be saved to ``~/.config/proxmox-backup/encryption-key.json``.
+
+2. Create an RSA public/private key pair:
+
+   .. code-block:: console
+
+     # proxmox-backup-client key create-master-key
+     Master Key Password: *********
+     ...
+
+   This will create two files in your current directory, ``master-public.pem``
+   and ``master-private.pem``.
+
+3. Import the newly created ``master-public.pem`` public certificate, so that
+   ``proxmox-backup-client`` can find and use it upon backup.
+
+   .. code-block:: console
+
+     # proxmox-backup-client key import-master-pubkey /path/to/master-public.pem
+     Imported public master key to "~/.config/proxmox-backup/master-public.pem"
+
+4. With all these files in place, run a backup job:
+
+   .. code-block:: console
+
+     # proxmox-backup-client backup etc.pxar:/etc
+
+   The key will be stored in your backup, under the name ``rsa-encrypted.key``.
+
+   .. Note:: The ``--keyfile`` parameter can be excluded, if the encryption key
+     is in the default path. If you specified another path upon creation, you
+     must pass the ``--keyfile`` parameter.
+
+5. To test that everything worked, you can restore the key from the backup:
+
+   .. code-block:: console
+
+     # proxmox-backup-client restore /path/to/backup/ rsa-encrypted.key /path/to/target
+
+   .. Note:: You should not need an encryption key to extract this file. However, if
+     a key exists at the default location
+     (``~/.config/proxmox-backup/encryption-key.json``) the program will prompt
+     you for an encryption key password. Simply moving ``encryption-key.json``
+     out of this directory will fix this issue.
+
+6. Then, use the previously generated master key to decrypt the file:
+
+   .. code-block:: console
+
+     # proxmox-backup-client key import-with-master-key /path/to/target --master-keyfile /path/to/master-private.pem --encrypted-keyfile /path/to/rsa-encrypted.key
+     Master Key Password: ******
+     New Password: ******
+     Verify Password: ******
+
+7. The target file will now contain the encryption key information in plain
+   text. The success of this can be confirmed by passing the resulting ``json``
+   file, with the ``--keyfile`` parameter, when decrypting files from the backup.
+
+.. warning:: Without their key, backed up files will be inaccessible. Thus, you should
+  keep keys ordered and in a place that is separate from the contents being
+  backed up. It can happen, for example, that you back up an entire system, using
+  a key on that system. If the system then becomes inaccessible for any reason
+  and needs to be restored, this will not be possible as the encryption key will be
+  lost along with the broken system.
+
+It is recommended that you keep your master key safe, but easily accessible, in
+order for quick disaster recovery. For this reason, the best place to store it
+is in your password manager, where it is immediately recoverable. As a backup to
+this, you should also save the key to a USB drive and store that in a secure
+place. This way, it is detached from any system, but is still easy to recover
+from, in case of emergency. Finally, in preparation for the worst case scenario,
+you should also consider keeping a paper copy of your master key locked away in
+a safe place. The ``paperkey`` subcommand can be used to create a QR encoded
+version of your master key. The following command sends the output of the
+``paperkey`` command to a text file, for easy printing.
+
+.. code-block:: console
+
+  proxmox-backup-client key paperkey --output-format text > qrkey.txt
+
+
+Restoring Data
+--------------
+
+The regular creation of backups is a necessary step 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
+list command provides a list of all the snapshots on the server:
+
+.. code-block:: console
+
+  # proxmox-backup-client snapshot list
+  ┌────────────────────────────────┬─────────────┬────────────────────────────────────┐
+  │ snapshot                       │        size │ files                              │
+  ╞════════════════════════════════╪═════════════╪════════════════════════════════════╡
+  │ host/elsa/2019-12-03T09:30:15Z │ 51788646825 │ root.pxar catalog.pcat1 index.json │
+  ├────────────────────────────────┼─────────────┼────────────────────────────────────┤
+  │ host/elsa/2019-12-03T09:35:01Z │ 51790622048 │ root.pxar catalog.pcat1 index.json │
+  ├────────────────────────────────┼─────────────┼────────────────────────────────────┤
+  ...
+
+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
+
+
+.. _changing-backup-owner:
+
+Changing the Owner of a Backup Group
+------------------------------------
+
+By default, the owner of a backup group is the user which was used to originally
+create that backup group (or in the case of sync jobs, ``root@pam``). This
+means that if a user ``mike@pbs`` created a backup, another user ``john@pbs``
+can not be used to create backups in that same backup group.  In case you want
+to change the owner of a backup, you can do so with the below command, using a
+user that has ``Datastore.Modify`` privileges on the datastore.
+
+.. code-block:: console
+
+  # proxmox-backup-client change-owner vm/103 john@pbs
+
+This can also be done from within the web interface, by navigating to the
+`Content` section of the datastore that contains the backup group and
+selecting the user icon under the `Actions` column. Common cases for this could
+be to change the owner of a sync job from ``root@pam``, or to repurpose a
+backup group.
+
+
+.. _backup-pruning:
+
+Pruning and Removing Backups
+----------------------------
+
+You can manually delete a backup snapshot using the ``forget``
+command:
+
+.. code-block:: console
+
+  # proxmox-backup-client snapshot forget <snapshot>
+
+
+.. caution:: This command removes all archives in this backup
+   snapshot. They will be inaccessible and unrecoverable.
+
+
+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

@@ -13,7 +13,7 @@ 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 systemds calendar events.
+They are mostly compatible with systemd's calendar events.
 
 The general format is as follows:
 
@@ -27,7 +27,7 @@ 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:
+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:
@@ -48,7 +48,7 @@ Value                              Syntax
 `daily`                            `*-*-* 00:00:00`
 `weekly`                           `mon *-*-* 00:00:00`
 `monthly`                          `*-*-01 00:00:00`
-`yearly` or `annualy`              `*-01-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`
 =================================  ==============================
@@ -80,7 +80,7 @@ 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
+* 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

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

@@ -74,7 +74,7 @@ rst_epilog = epilog_file.read()
 
 # General information about the project.
 project = 'Proxmox Backup'
-copyright = '2019-2020, Proxmox Server Solutions GmbH'
+copyright = '2019-2021, Proxmox Server Solutions GmbH'
 author = 'Proxmox Support Team'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -171,6 +171,8 @@ html_theme_options = {
     'extra_nav_links': {
         'Proxmox Homepage': 'https://proxmox.com',
         'PDF': 'proxmox-backup.pdf',
+        'Prune Simulator' : 'prune-simulator/index.html',
+        'LTO Barcode Generator' : 'lto-barcode/index.html',
     },
 
     'sidebar_width': '320px',
@@ -228,6 +230,10 @@ html_favicon = 'images/favicon.ico'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_js_files = [
+    'custom.js',
+]
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.

docs/custom.js

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

docs/epilog.rst

@@ -1,6 +1,6 @@
 .. Epilog (included at top of each file)
    
-   We use this file to define external links and commone replacement
+   We use this file to define external links and common replacement
    patterns.
 
 .. |VERSION| replace:: 1.0

docs/faq.rst

@@ -27,14 +27,14 @@ 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                |
+|Proxmox Backup 1.x     | Debian 10 (Buster) | 2020-11       | tba        | tba                |
 +-----------------------+--------------------+---------------+------------+--------------------+
 
 
 Can I copy or synchronize my datastore to another location?
 -----------------------------------------------------------
 
-Proxmox Backup Server allows you to copy or synchroize datastores to other
+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
@@ -53,9 +53,12 @@ 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
+Proxmox Backup Server transfers data via `Transport Layer Security (TLS)
-encrypted before it reaches the server. Thus, in the event that an attacker
+<https://en.wikipedia.org/wiki/Transport_Layer_Security>`_ and additionally
-gains access to the server, they will not be able to read the data.
+supports client-side encryption. This means that data is transferred securely
+and can be encrypted before it reaches the server.  Thus, in the event that an
+attacker gains access to the server or any point of the network, they will not
+be able to read the data.
 
 .. note:: Encryption is not enabled by default. To set up encryption, see the
   `Encryption

docs/gui.rst

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

docs/index.rst

@@ -22,8 +22,18 @@ in the section entitled "GNU Free 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
+   technical-overview.rst
    faq.rst
 
 .. raw:: latex

docs/installation.rst

@@ -5,9 +5,11 @@ Installation
 can either be installed with a graphical installer or on top of
 Debian_ from the provided package repository.
 
+.. include:: system-requirements.rst
+
 .. include:: package-repositories.rst
 
-Server installation
+Server Installation
 -------------------
 
 The backup server stores the actual backed up data and provides a web based GUI
@@ -35,22 +37,21 @@ 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
+  disk(s) with ext4, xfs or ZFS, and installs the operating system
-  system
 
 * Complete operating system (Debian Linux, 64-bit)
 
-* Our Linux kernel with ZFS support
+* Proxmox Linux kernel with ZFS support
 
 * Complete tool-set to administer backups and all necessary resources
 
-* Web based GUI management interface
+* Web based management interface
 
 .. note:: During the installation process, the complete server
    is used by default and all existing data is removed.
 
 
-Install `Proxmox Backup`_ server on Debian
+Install `Proxmox Backup`_ Server on Debian
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Proxmox ships as a set of Debian packages which can be installed on top of a
@@ -82,11 +83,11 @@ support, and a set of common and useful packages.
   when LVM_ or ZFS_ is used. The network configuration is completely up to you
   as well.
 
-.. note:: You can access the webinterface of the Proxmox Backup Server with
+.. Note:: You can access the web interface of the Proxmox Backup Server with
-  your web browser, using HTTPS on port 8007. For example at
+   your web browser, using HTTPS on port 8007. For example at
- ``https://<ip-or-dns-name>:8007``
+   ``https://<ip-or-dns-name>:8007``
 
-Install Proxmox Backup server on `Proxmox VE`_
+Install Proxmox Backup Server on `Proxmox VE`_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After configuring the
@@ -102,14 +103,14 @@ After configuring the
    server to store backups. Should the hypervisor server fail, you can
    still access the backups.
 
-.. note::
+.. Note:: You can access the web interface of the Proxmox Backup Server with
-  You can access the webinterface of the Proxmox Backup Server with your web
+   your web browser, using HTTPS on port 8007. For example at
-  browser, using HTTPS on port 8007. For example at ``https://<ip-or-dns-name>:8007``
+   ``https://<ip-or-dns-name>:8007``
 
-Client installation
+Client Installation
 -------------------
 
-Install `Proxmox Backup`_ client on Debian
+Install `Proxmox Backup`_ Client on Debian
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Proxmox ships as a set of Debian packages to be installed on

docs/introduction.rst

@@ -1,8 +1,8 @@
 Introduction
 ============
 
-What is Proxmox Backup Server
+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
@@ -10,13 +10,16 @@ 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.
 
-Proxmox Backup Server supports deduplication, compression, and authenticated
+It 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.
 
-It features strong client-side encryption. Thus, it's possible to
+Proxmox Backup uses state of the art cryptography for both client-server
-backup data to targets that are not fully trusted.
+communication and backup content :ref:`encryption <encryption>`. All
-
+client-server communication uses `TLS
+<https://en.wikipedia.org/wiki/Transport_Layer_Security>`_, and backup data can
+be encrypted on the client-side before sending, making it safer to back up data
+to targets that are not fully trusted.
 
 Architecture
 ------------
@@ -63,8 +66,9 @@ Main Features
    several gigabytes of data per second.
 
 :Encryption: Backups can be encrypted on the client-side, using AES-256 in
-   Galois/Counter Mode (GCM_) mode. This authenticated encryption (AE_) mode
+   Galois/Counter Mode (GCM_). This authenticated encryption (AE_) mode
-   provides very high performance on modern hardware.
+   provides very high performance on modern hardware. In addition to client-side
+   encryption, all data is transferred via a secure TLS connection.
 
 :Web interface: Manage the Proxmox Backup Server with the integrated, web-based
    user interface.
@@ -104,7 +108,7 @@ Software Stack
 
 Proxmox Backup Server consists of multiple components:
 
-* A server-daemon providing, among other things, a RESTfull API, super-fast
+* 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
@@ -125,7 +129,7 @@ language.
 
  -- `The Rust Programming Language <https://doc.rust-lang.org/book/ch00-00-introduction.html>`_
 
-.. todo:: further explain the software stack
+.. _get_help:
 
 Getting Help
 ------------
@@ -157,7 +161,7 @@ of the issue and will send a notification once it has been solved.
 License
 -------
 
-Copyright (C) 2019-2020 Proxmox Server Solutions GmbH
+Copyright (C) 2019-2021 Proxmox Server Solutions GmbH
 
 This software is written by Proxmox Server Solutions GmbH <support@proxmox.com>
 
@@ -178,5 +182,28 @@ along with this program.  If not, see AGPL3_.
 History
 -------
 
-.. todo:: Add development History of the product
+Backup is, and always has been, a central aspect of IT administration.
+The need to recover from data loss is fundamental and only increases with
+virtualization.
 
+For this reason, we've been shipping a backup tool with Proxmox VE, from the
+beginning. This tool is called ``vzdump`` and is able to make
+consistent snapshots of running LXC containers and KVM virtual
+machines.
+
+However, ``vzdump`` only allows for full backups. While this is fine
+for small backups, it becomes a burden for users with large VMs. Both
+backup duration and storage usage are too high for this case, especially
+for users who want to keep many backups of the same VMs. To solve these
+problems, we needed to offer deduplication and incremental backups.
+
+Back in October 2018, development started. We investigated
+several technologies and frameworks and finally decided to use
+:term:`Rust` as the implementation language, in order to provide high speed and
+memory efficiency. The 2018-edition of Rust seemed promising for our
+requirements.
+
+In July 2020, we released the first beta version of Proxmox Backup
+Server, followed by the first stable version in November 2020. With support for
+incremental, fully deduplicated backups, Proxmox Backup significantly reduces
+network load and saves valuable storage space.

docs/local-zfs.rst

@@ -220,7 +220,7 @@ and you can install it using `apt-get`:
   # apt-get install zfs-zed
 
 To activate the daemon it is necessary to edit `/etc/zfs/zed.d/zed.rc` with your
-favourite editor, and uncomment the `ZED_EMAIL_ADDR` setting:
+favorite editor, and uncomment the `ZED_EMAIL_ADDR` setting:
 
 .. code-block:: console
 
@@ -262,7 +262,7 @@ 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 swapdevice.
+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:
@@ -312,6 +312,8 @@ You can disable compression at any time with:
 
 Only new blocks will be affected by this change.
 
+.. _local_zfs_special_device:
+
 ZFS Special Device
 ^^^^^^^^^^^^^^^^^^
 

docs/lto-barcode/code39.js

@@ -0,0 +1,351 @@
+// Code39 barcode generator
+// see https://en.wikipedia.org/wiki/Code_39
+
+// IBM LTO Ultrium Cartridge Label Specification
+// http://www-01.ibm.com/support/docview.wss?uid=ssg1S7000429
+
+let code39_codes = {
+    "1": ['B', 's', 'b', 'S', 'b', 's', 'b', 's', 'B'],
+    "A": ['B', 's', 'b', 's', 'b', 'S', 'b', 's', 'B'],
+    "K": ['B', 's', 'b', 's', 'b', 's', 'b', 'S', 'B'],
+    "U": ['B', 'S', 'b', 's', 'b', 's', 'b', 's', 'B'],
+
+    "2": ['b', 's', 'B', 'S', 'b', 's', 'b', 's', 'B'],
+    "B": ['b', 's', 'B', 's', 'b', 'S', 'b', 's', 'B'],
+    "L": ['b', 's', 'B', 's', 'b', 's', 'b', 'S', 'B'],
+    "V": ['b', 'S', 'B', 's', 'b', 's', 'b', 's', 'B'],
+
+    "3": ['B', 's', 'B', 'S', 'b', 's', 'b', 's', 'b'],
+    "C": ['B', 's', 'B', 's', 'b', 'S', 'b', 's', 'b'],
+    "M": ['B', 's', 'B', 's', 'b', 's', 'b', 'S', 'b'],
+    "W": ['B', 'S', 'B', 's', 'b', 's', 'b', 's', 'b'],
+
+    "4": ['b', 's', 'b', 'S', 'B', 's', 'b', 's', 'B'],
+    "D": ['b', 's', 'b', 's', 'B', 'S', 'b', 's', 'B'],
+    "N": ['b', 's', 'b', 's', 'B', 's', 'b', 'S', 'B'],
+    "X": ['b', 'S', 'b', 's', 'B', 's', 'b', 's', 'B'],
+
+    "5": ['B', 's', 'b', 'S', 'B', 's', 'b', 's', 'b'],
+    "E": ['B', 's', 'b', 's', 'B', 'S', 'b', 's', 'b'],
+    "O": ['B', 's', 'b', 's', 'B', 's', 'b', 'S', 'b'],
+    "Y": ['B', 'S', 'b', 's', 'B', 's', 'b', 's', 'b'],
+
+    "6": ['b', 's', 'B', 'S', 'B', 's', 'b', 's', 'b'],
+    "F": ['b', 's', 'B', 's', 'B', 'S', 'b', 's', 'b'],
+    "P": ['b', 's', 'B', 's', 'B', 's', 'b', 'S', 'b'],
+    "Z": ['b', 'S', 'B', 's', 'B', 's', 'b', 's', 'b'],
+
+    "7": ['b', 's', 'b', 'S', 'b', 's', 'B', 's', 'B'],
+    "G": ['b', 's', 'b', 's', 'b', 'S', 'B', 's', 'B'],
+    "Q": ['b', 's', 'b', 's', 'b', 's', 'B', 'S', 'B'],
+    "-": ['b', 'S', 'b', 's', 'b', 's', 'B', 's', 'B'],
+
+    "8": ['B', 's', 'b', 'S', 'b', 's', 'B', 's', 'b'],
+    "H": ['B', 's', 'b', 's', 'b', 'S', 'B', 's', 'b'],
+    "R": ['B', 's', 'b', 's', 'b', 's', 'B', 'S', 'b'],
+    ".": ['B', 'S', 'b', 's', 'b', 's', 'B', 's', 'b'],
+
+    "9": ['b', 's', 'B', 'S', 'b', 's', 'B', 's', 'b'],
+    "I": ['b', 's', 'B', 's', 'b', 'S', 'B', 's', 'b'],
+    "S": ['b', 's', 'B', 's', 'b', 's', 'B', 'S', 'b'],
+    " ": ['b', 'S', 'B', 's', 'b', 's', 'B', 's', 'b'],
+
+    "0": ['b', 's', 'b', 'S', 'B', 's', 'B', 's', 'b'],
+    "J": ['b', 's', 'b', 's', 'B', 'S', 'B', 's', 'b'],
+    "T": ['b', 's', 'b', 's', 'B', 's', 'B', 'S', 'b'],
+    "*": ['b', 'S', 'b', 's', 'B', 's', 'B', 's', 'b']
+};
+
+let colors = [
+    '#BB282E',
+    '#FAE54A',
+    '#9AC653',
+    '#01A5E2',
+    '#9EAAB6',
+    '#D97E35',
+    '#E27B99',
+    '#67A945',
+    '#F6B855',
+    '#705A81'
+];
+
+let lto_label_width = 70;
+let lto_label_height = 17;
+
+function foreach_label(page_layout, callback) {
+
+    let count = 0;
+    let row = 0;
+    let height = page_layout.margin_top;
+
+    while ((height + page_layout.label_height) <= page_layout.page_height) {
+
+	let column = 0;
+	let width = page_layout.margin_left;
+
+	while ((width + page_layout.label_width) <= page_layout.page_width) {
+
+	    callback(column, row, count, width, height);
+	    count += 1;
+
+	    column += 1;
+	    width += page_layout.label_width;
+	    width += page_layout.column_spacing;
+	}
+
+	row += 1;
+	height += page_layout.label_height;
+	height += page_layout.row_spacing;
+    }
+
+}
+
+function compute_max_labels(page_layout) {
+
+    let max_labels = 0;
+    foreach_label(page_layout, function() { max_labels += 1; });
+    return max_labels;
+}
+
+function svg_label(mode, label, label_type, pagex, pagey, label_borders) {
+    let svg = "";
+
+    if (label.length != 6) {
+	throw "wrong label length";
+    }
+    if (label_type.length != 2) {
+	throw "wrong label_type length";
+    }
+
+    let ratio = 2.75;
+    let parts = 3*ratio + 6; // 3*wide + 6*small;
+    let barcode_width = (lto_label_width/12)*10; // 10*code + 2margin
+    let small = barcode_width/(parts*10 + 9);
+    let code_width = small*parts;
+    let wide = small*ratio;
+    let xpos = pagex + code_width;
+    let height = 12;
+
+    if (mode === 'placeholder') {
+	if (label_borders) {
+	    svg += `<rect class='unprintable' x='${pagex}' y='${pagey}' width='${lto_label_width}' height='${lto_label_height}' fill='none' style='stroke:black;stroke-width:0.1;'/>`;
+	}
+	return svg;
+    }
+    if (label_borders) {
+	svg += `<rect x='${pagex}' y='${pagey}' width='${lto_label_width}' height='${lto_label_height}' fill='none' style='stroke:black;stroke-width:0.1;'/>`;
+    }
+
+    if (mode === "color" || mode == "frame") {
+	let w = lto_label_width/8;
+	let h = lto_label_height - height;
+	for (var i = 0; i < 7; i++) {
+	    let textx = w/2 + pagex + i*w;
+	    let texty = pagey;
+
+	    let fill = "none";
+	    if (mode === "color" && (i < 6)) {
+		let letter = label.charAt(i);
+		if (letter >= '0' && letter <= '9') {
+		    fill = colors[parseInt(letter, 10)];
+		}
+	    }
+
+	    svg += `<rect x='${textx}' y='${texty}' width='${w}' height='${h}' style='stroke:black;stroke-width:0.2;fill:${fill};'/>`;
+
+	    if (i == 6) {
+		textx += 3;
+		texty += 3.7;
+		svg += `<text x='${textx}' y='${texty}' style='font-weight:bold;font-size:3px;font-family:sans-serif;'>${label_type}</text>`;
+	    } else {
+		let letter = label.charAt(i);
+		textx += 3.5;
+		texty += 4;
+		svg += `<text x='${textx}' y='${texty}' style='font-weight:bold;font-size:4px;font-family:sans-serif;'>${letter}</text>`;
+	    }
+	}
+    }
+
+    let raw_label = `*${label}${label_type}*`;
+
+    for (var i = 0; i < raw_label.length; i++) {
+	let letter = raw_label.charAt(i);
+
+	let code = code39_codes[letter];
+	if (code === undefined) {
+	    throw `unable to encode letter '${letter}' with code39`;
+	}
+
+	if (mode === "simple") {
+	    let textx = xpos + code_width/2;
+	    let texty = pagey + 4;
+
+	    if (i > 0 && (i+1) < raw_label.length) {
+		svg += `<text x='${textx}' y='${texty}' style='font-weight:bold;font-size:4px;font-family:sans-serif;'>${letter}</text>`;
+	    }
+	}
+
+	for (let c of code) {
+
+	    if (c === 's') {
+		xpos += small;
+		continue;
+	    }
+	    if (c === 'S') {
+		xpos += wide;
+		continue;
+	    }
+
+	    let w = c === 'B' ? wide : small;
+	    let ypos = pagey + lto_label_height - height;
+
+	    svg += `<rect x='${xpos}' y='${ypos}' width='${w}' height='${height}' style='fill:black'/>`;
+	    xpos = xpos + w;
+	}
+	xpos += small;
+    }
+
+    return svg;
+}
+
+function html_page_header() {
+    let html = "<html5>";
+
+    html += "<style>";
+
+    /* no page margins */
+    html += "@page{margin-left: 0px;margin-right: 0px;margin-top: 0px;margin-bottom: 0px;}";
+    /* to hide things on printed page */
+    html +=  "@media print { .unprintable { visibility: hidden;	} }";
+
+    html += "</style>";
+
+    //html += "<body onload='window.print()'>";
+    html += "<body style='background-color: white;'>";
+
+    return html;
+}
+
+function svg_page_header(page_width, page_height) {
+    let svg = "<svg version='1.1' xmlns='http://www.w3.org/2000/svg'";
+    svg += ` width='${page_width}mm' height='${page_height}mm' viewBox='0 0 ${page_width} ${page_height}'>`;
+
+    return svg;
+}
+
+function printBarcodePage() {
+    let frame = document.getElementById("print_frame");
+
+    let window = frame.contentWindow;
+    window.print();
+}
+
+function generate_barcode_page(target_id, page_layout, label_list, calibration) {
+
+    let svg = svg_page_header(page_layout.page_width, page_layout.page_height);
+
+    let c = calibration;
+
+    console.log(calibration);
+
+    svg += "<g id='barcode_page'";
+    if (c !== undefined) {
+	svg += ` transform='scale(${c.scalex}, ${c.scaley}),translate(${c.offsetx}, ${c.offsety})'`;
+    }
+    svg += '>';
+
+    foreach_label(page_layout, function(column, row, count, xpos, ypos) {
+
+	if (count >= label_list.length) { return; }
+
+	let item = label_list[count];
+
+	svg += svg_label(item.mode, item.label, item.tape_type, xpos, ypos, page_layout.label_borders);
+    });
+
+    svg += "</g>";
+    svg += "</svg>";
+
+    let html = html_page_header();
+    html += svg;
+    html += "</body>";
+    html += "</html>";
+
+    let frame = document.getElementById(target_id);
+
+    setupPrintFrame(frame, page_layout.page_width, page_layout.page_height);
+
+    let fwindow = frame.contentWindow;
+
+    fwindow.document.open();
+    fwindow.document.write(html);
+    fwindow.document.close();
+}
+
+function setupPrintFrame(frame, page_width, page_height) {
+    let dpi = 98;
+
+    let dpr = window.devicePixelRatio;
+    if (dpr !== undefined) {
+	dpi = dpi*dpr;
+    }
+
+    let ppmm = dpi/25.4;
+
+    frame.width = page_width*ppmm;
+    frame.height = page_height*ppmm;
+}
+
+function generate_calibration_page(target_id, page_layout, calibration) {
+
+    let frame = document.getElementById(target_id);
+
+    setupPrintFrame(frame, page_layout.page_width, page_layout.page_height);
+
+    let svg = svg_page_header( page_layout.page_width,  page_layout.page_height);
+
+    svg += "<defs>";
+    svg += "<marker id='endarrow' markerWidth='10' markerHeight='7' ";
+    svg += "refX='10' refY='3.5' orient='auto'><polygon points='0 0, 10 3.5, 0 7' />";
+    svg += "</marker>";
+
+    svg += "<marker id='startarrow' markerWidth='10' markerHeight='7' ";
+    svg += "refX='0' refY='3.5' orient='auto'><polygon points='10 0, 10 7, 0 3.5' />";
+    svg += "</marker>";
+    svg += "</defs>";
+
+    svg += "<rect x='50' y='50' width='100' height='100' style='fill:none;stroke-width:0.05;stroke:rgb(0,0,0)'/>";
+
+    let text_style = "style='font-weight:bold;font-size:4;font-family:sans-serif;'";
+
+    svg += `<text x='10' y='99' ${text_style}>Sx = 50mm</text>`;
+    svg += "<line x1='0' y1='100' x2='50' y2='100' stroke='#000' marker-end='url(#endarrow)' stroke-width='.25'/>";
+
+    svg += `<text x='60' y='99' ${text_style}>Dx = 100mm</text>`;
+    svg += "<line x1='50' y1='100' x2='150' y2='100' stroke='#000' marker-start='url(#startarrow)' marker-end='url(#endarrow)' stroke-width='.25'/>";
+
+    svg += `<text x='142' y='10' ${text_style} writing-mode='tb'>Sy = 50mm</text>`;
+    svg += "<line x1='140' y1='0' x2='140' y2='50' stroke='#000' marker-end='url(#endarrow)' stroke-width='.25'/>";
+
+    svg += `<text x='142' y='60' ${text_style} writing-mode='tb'>Dy = 100mm</text>`;
+    svg += "<line x1='140' y1='50' x2='140' y2='150' stroke='#000' marker-start='url(#startarrow)' marker-end='url(#endarrow)' stroke-width='.25'/>";
+
+    let c = calibration;
+    if (c !== undefined) {
+	svg += `<rect x='50' y='50' width='100' height='100' style='fill:none;stroke-width:0.05;stroke:rgb(255,0,0)' `;
+	svg += `transform='scale(${c.scalex}, ${c.scaley}),translate(${c.offsetx}, ${c.offsety})'/>`;
+    }
+
+    svg += "</svg>";
+
+    let html = html_page_header();
+    html += svg;
+    html += "</body>";
+    html += "</html>";
+
+    let fwindow = frame.contentWindow;
+
+    fwindow.document.open();
+    fwindow.document.write(html);
+    fwindow.document.close();
+}

docs/lto-barcode/index.html

@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
+  <title>Proxmox LTO Barcode Label Generator</title>
+  <link rel="stylesheet" type="text/css" href="extjs/theme-crisp/resources/theme-crisp-all.css">
+  <style>
+    /* fix action column icons */
+    .x-action-col-icon {
+	font-size: 13px;
+	height: 13px;
+    }
+    .x-grid-cell-inner-action-col {
+	padding: 6px 10px 5px;
+    }
+    .x-action-col-icon:before {
+	color: #555;
+    }
+    .x-action-col-icon  {
+	color: #21BF4B;
+    }
+    .x-action-col-icon {
+	margin: 0 1px;
+	font-size: 14px;
+    }
+    .x-action-col-icon:before, .x-action-col-icon:after {
+	font-size: 14px;
+    }
+    .x-action-col-icon:hover:before, .x-action-col-icon:hover:after {
+	text-shadow: 1px 1px 1px #AAA;
+	font-weight: 800;
+    }
+  </style>
+  <link rel="stylesheet" type="text/css" href="font-awesome/css/font-awesome.css"/>
+  <script type="text/javascript" src="extjs/ext-all.js"></script>
+  
+  <script type="text/javascript" src="code39.js"></script>
+  <script type="text/javascript" src="prefix-field.js"></script>
+  <script type="text/javascript" src="label-style.js"></script>
+  <script type="text/javascript" src="tape-type.js"></script>
+  <script type="text/javascript" src="paper-size.js"></script>
+  <script type="text/javascript" src="page-layout.js"></script>
+  <script type="text/javascript" src="page-calibration.js"></script>
+  <script type="text/javascript" src="label-list.js"></script>
+  <script type="text/javascript" src="label-setup.js"></script>
+  <script type="text/javascript" src="lto-barcode.js"></script>
+</head>
+<body>
+</body>
+</html>

docs/lto-barcode/label-list.js

@@ -0,0 +1,140 @@
+Ext.define('LabelList', {
+    extend: 'Ext.grid.Panel',
+    alias: 'widget.labelList',
+
+    plugins: {
+        ptype: 'cellediting',
+        clicksToEdit: 1
+    },
+
+    selModel: 'cellmodel',
+
+    store: {
+	field: [
+	    'prefix',
+	    'tape_type',
+	    {
+		type: 'integer',
+		name: 'start',
+	    },
+	    {
+		type: 'integer',
+		name: 'end',
+	    },
+	],
+	data: [],
+    },
+
+    listeners: {
+	validateedit: function(editor, context) {
+	    console.log(context.field);
+	    console.log(context.value);
+	    context.record.set(context.field, context.value);
+	    context.record.commit();
+	    return true;
+	},
+    },
+
+    columns: [
+	{
+            text: 'Prefix',
+            dataIndex: 'prefix',
+	    flex: 1,
+	    editor: {
+		xtype: 'prefixfield',
+		allowBlank: false,
+	    },
+	    renderer: function (value, metaData, record) {
+		console.log(record);
+		if (record.data.mode === 'placeholder') {
+		    return "-";
+		}
+		return value;
+	    },
+	},
+	{
+            text: 'Type',
+            dataIndex: 'tape_type',
+	    flex: 1,
+	    editor: {
+		xtype: 'ltoTapeType',
+		allowBlank: false,
+	    },
+	    renderer: function (value, metaData, record) {
+		console.log(record);
+		if (record.data.mode === 'placeholder') {
+		    return "-";
+		}
+		return value;
+	    },
+	},
+	{
+            text: 'Mode',
+            dataIndex: 'mode',
+	    flex: 1,
+	    editor: {
+		xtype: 'ltoLabelStyle',
+		allowBlank: false,
+	    },
+	},
+	{
+	    text: 'Start',
+	    dataIndex: 'start',
+	    flex: 1,
+	    editor: {
+		xtype: 'numberfield',
+		allowBlank: false,
+	    },
+	},
+	{
+	    text: 'End',
+	    dataIndex: 'end',
+	    flex: 1,
+	    editor: {
+		xtype: 'numberfield',
+	    },
+	    renderer: function(value) {
+		if (value === null || value === '' || value === undefined) {
+		    return "Fill";
+		}
+		return value;
+	    },
+	},
+	{
+	    xtype: 'actioncolumn',
+	    width: 75,
+	    items: [
+		{
+		    tooltip: 'Move Up',
+		    iconCls: 'fa fa-arrow-up',
+		    handler: function(grid, rowIndex) {
+			if (rowIndex < 1) { return; }
+			let store = grid.getStore();
+			let record = store.getAt(rowIndex);
+			store.removeAt(rowIndex);
+			store.insert(rowIndex - 1, record);
+		    },
+		},
+		{
+		    tooltip: 'Move Down',
+		    iconCls: 'fa fa-arrow-down',
+		    handler: function(grid, rowIndex) {
+			let store = grid.getStore();
+			if (rowIndex >= store.getCount()) { return; }
+			let record = store.getAt(rowIndex);
+			store.removeAt(rowIndex);
+			store.insert(rowIndex + 1, record);
+		    },
+		},
+		{
+		    tooltip: 'Delete',
+		    iconCls: 'fa fa-scissors',
+		    //iconCls: 'fa critical fa-trash-o',
+		    handler: function(grid, rowIndex) {
+			grid.getStore().removeAt(rowIndex);
+		    },
+		}
+	    ],
+	},
+    ],
+});

docs/lto-barcode/label-setup.js

@@ -0,0 +1,107 @@
+Ext.define('LabelSetupPanel', {
+    extend: 'Ext.panel.Panel',
+    alias: 'widget.labelSetupPanel',
+
+    layout: {
+	type: 'hbox',
+	align: 'stretch',
+	pack: 'start',
+    },
+
+    getValues: function() {
+	let me = this;
+
+	let values = {};
+
+	Ext.Array.each(me.query('[isFormField]'), function(field) {
+	    let data = field.getSubmitData();
+	    Ext.Object.each(data, function(name, val) {
+		let parsed = parseInt(val, 10);
+		values[name] = isNaN(parsed) ? val : parsed;
+	    });
+	});
+
+	return values;
+    },
+
+    controller: {
+	xclass: 'Ext.app.ViewController',
+
+	init: function() {
+	    let me = this;
+	    let view = me.getView();
+	    let list = view.down("labelList");
+	    let store = list.getStore();
+	    store.on('datachanged', function(store) {
+		view.fireEvent("listchanged", store);
+	    });
+	    store.on('update', function(store) {
+		view.fireEvent("listchanged", store);
+	    });
+	},
+
+	onAdd: function() {
+	    let list = this.lookupReference('label_list');
+	    let view = this.getView();
+	    let params = view.getValues();
+	    list.getStore().add(params);
+	},
+    },
+
+    items: [
+	{
+	    border: false,
+	    layout: {
+		type: 'vbox',
+		align: 'stretch',
+		pack: 'start',
+	    },
+	    items: [
+		{
+		    xtype: 'prefixfield',
+		    name: 'prefix',
+		    value: 'TEST',
+		    fieldLabel: 'Prefix',
+		},
+		{
+		    xtype: 'ltoTapeType',
+		    name: 'tape_type',
+		    fieldLabel: 'Type',
+		    value: 'L8',
+		},
+		{
+		    xtype: 'ltoLabelStyle',
+		    name: 'mode',
+		    fieldLabel: 'Mode',
+		    value: 'color',
+		},
+		{
+		    xtype: 'numberfield',
+		    name: 'start',
+		    fieldLabel: 'Start',
+		    minValue: 0,
+		    allowBlank: false,
+		    value: 0,
+		},
+		{
+		    xtype: 'numberfield',
+		    name: 'end',
+		    fieldLabel: 'End',
+		    minValue: 0,
+		    emptyText: 'Fill',
+		},
+		{
+		    xtype: 'button',
+		    text: 'Add',
+		    handler: 'onAdd',
+		},
+	    ],
+	},
+	{
+	    margin: "0 0 0 10",
+	    xtype: 'labelList',
+	    reference: 'label_list',
+	    flex: 1,
+	},
+    ],
+});

docs/lto-barcode/label-style.js

@@ -0,0 +1,20 @@
+Ext.define('LtoLabelStyle', {
+    extend: 'Ext.form.field.ComboBox',
+    alias: 'widget.ltoLabelStyle',
+
+    editable: false,
+
+    displayField: 'text',
+    valueField: 'value',
+    queryMode: 'local',
+
+    store: {
+	field: ['value', 'text'],
+	data: [
+	    { value: 'simple', text: "Simple" },
+	    { value: 'color', text: 'Color (frames with color)' },
+	    { value: 'frame', text: 'Frame (no color)' },
+	    { value: 'placeholder', text: 'Placeholder (empty)' },
+	],
+    },
+});

docs/lto-barcode/lto-barcode.js

@@ -0,0 +1,214 @@
+// FIXME: HACK! Makes scrolling in number spinner work again. fixed in ExtJS >= 6.1
+if (Ext.isFirefox) {
+    Ext.$eventNameMap.DOMMouseScroll = 'DOMMouseScroll';
+}
+
+function draw_labels(target_id, label_list, page_layout, calibration) {
+
+    let max_labels = compute_max_labels(page_layout);
+
+    let count_fixed = 0;
+    let count_fill = 0;
+
+    for (i = 0; i < label_list.length; i++) {
+	let item = label_list[i];
+	if (item.end === null || item.end === '' || item.end === undefined) {
+	    count_fill += 1;
+	    continue;
+	}
+	if (item.end <= item.start) {
+	    count_fixed += 1;
+	    continue;
+	}
+	count_fixed += (item.end - item.start) + 1;
+    }
+
+    let rest = max_labels - count_fixed;
+    let fill_size = 1;
+    if (rest >= count_fill) {
+	fill_size = Math.floor(rest/count_fill);
+    }
+
+    let list = [];
+
+    let count_fill_2 = 0;
+
+    for (i = 0; i < label_list.length; i++) {
+	let item = label_list[i];
+	let count;
+	if (item.end === null || item.end === '' || item.end === undefined) {
+	    count_fill_2 += 1;
+	    if (count_fill_2 === count_fill) {
+		count = rest;
+	    } else {
+		count = fill_size;
+	    }
+	    rest -= count;
+	} else {
+	    if (item.end <= item.start) {
+		count = 1;
+	    } else {
+		count = (item.end - item.start) + 1;
+	    }
+	}
+
+	for (j = 0; j < count; j++) {
+
+	    let id = item.start + j;
+
+	    if (item.prefix.length == 6) {
+
+		list.push({
+		    label: item.prefix,
+		    tape_type: item.tape_type,
+		    mode: item.mode,
+		    id: id,
+		});
+		rest += count - j - 1;
+		break;
+
+	    } else {
+
+		let pad_len = 6-item.prefix.length;
+		let label = item.prefix + id.toString().padStart(pad_len, 0);
+
+		if (label.length != 6) {
+		    rest += count - j;
+		    break;
+		}
+
+		list.push({
+		    label: label,
+		    tape_type: item.tape_type,
+		    mode: item.mode,
+		    id: id,
+		});
+	    }
+	}
+    }
+
+    generate_barcode_page(target_id, page_layout, list, calibration);
+}
+
+Ext.define('MainView', {
+    extend: 'Ext.container.Viewport',
+    alias: 'widget.mainview',
+
+    layout: {
+	type: 'vbox',
+	align: 'stretch',
+	pack: 'start',
+    },
+    width: 800,
+
+    controller: {
+	xclass: 'Ext.app.ViewController',
+
+	update_barcode_preview: function() {
+	    let me = this;
+	    let view = me.getView();
+	    let list_view = view.down("labelList");
+
+	    let store = list_view.getStore();
+	    let label_list = [];
+	    store.each((record) => {
+		label_list.push(record.data);
+	    });
+
+	    let page_layout_view =  view.down("pageLayoutPanel");
+	    let page_layout = page_layout_view.getValues();
+
+	    let calibration_view =  view.down("pageCalibration");
+	    let page_calibration = calibration_view.getValues();
+
+	    draw_labels("print_frame", label_list, page_layout, page_calibration);
+	},
+
+	update_calibration_preview: function() {
+	    let me = this;
+	    let view = me.getView();
+	    let page_layout_view =  view.down("pageLayoutPanel");
+	    let page_layout = page_layout_view.getValues();
+
+	    let calibration_view =  view.down("pageCalibration");
+	    let page_calibration = calibration_view.getValues();
+	    console.log(page_calibration);
+	    generate_calibration_page('print_frame', page_layout, page_calibration);
+	},
+
+	control: {
+	    labelSetupPanel: {
+		listchanged: function(store) {
+		    this.update_barcode_preview();
+		},
+		activate: function() {
+		    this.update_barcode_preview();
+		},
+	    },
+	    pageLayoutPanel: {
+		pagechanged: function(layout) {
+		    this.update_barcode_preview();
+		},
+		activate: function() {
+		    this.update_barcode_preview();
+		},
+	    },
+	    pageCalibration: {
+		calibrationchanged: function() {
+		    this.update_calibration_preview();
+		},
+		activate: function() {
+		    this.update_calibration_preview();
+		},
+	    },
+	},
+    },
+
+    items: [
+	{
+	    xtype: 'tabpanel',
+	    items: [
+		{
+		    xtype: 'labelSetupPanel',
+		    title: 'Proxmox LTO Barcode Label Generator',
+		    bodyPadding: 10,
+		},
+		{
+		    xtype: 'pageLayoutPanel',
+		    title: 'Page Layout',
+		    bodyPadding: 10,
+		},
+		{
+		    xtype: 'pageCalibration',
+		    title: 'Printer Calibration',
+		    bodyPadding: 10,
+		},
+	    ],
+	},
+	{
+	    xtype: 'panel',
+	    layout: "center",
+	    title: 'Print Preview',
+	    bodyStyle: "background-color: grey;",
+	    bodyPadding: 10,
+	    html: '<center><iframe id="print_frame" frameBorder="0"></iframe></center>',
+	    border: false,
+	    flex: 1,
+	    scrollable: true,
+	    tools:[{
+		type: 'print',
+		tooltip: 'Open Print Dialog',
+		handler: function(event, toolEl, panelHeader) {
+		    printBarcodePage();
+		}
+	    }],
+	},
+    ],
+});
+
+Ext.onReady(function() {
+
+    Ext.create('MainView', {
+	renderTo: Ext.getBody(),
+    });
+});

docs/lto-barcode/page-calibration.js

@@ -0,0 +1,142 @@
+Ext.define('PageCalibration', {
+    extend: 'Ext.panel.Panel',
+    alias: 'widget.pageCalibration',
+
+    layout: {
+	type: 'hbox',
+	align: 'stretch',
+	pack: 'start',
+    },
+
+    getValues: function() {
+	let me = this;
+
+	let values = {};
+
+	Ext.Array.each(me.query('[isFormField]'), function(field) {
+	    if (field.isValid()) {
+		let data = field.getSubmitData();
+		Ext.Object.each(data, function(name, val) {
+		    let parsed = parseFloat(val, 10);
+		    values[name] = isNaN(parsed) ? val : parsed;
+		});
+	    }
+	});
+
+	if (values.d_x === undefined) { return; }
+	if (values.d_y === undefined) { return; }
+	if (values.s_x === undefined) { return; }
+	if (values.s_y === undefined) { return; }
+
+	scalex = 100/values.d_x;
+	scaley = 100/values.d_y;
+
+	let offsetx = ((50*scalex) - values.s_x)/scalex;
+	let offsety = ((50*scaley) - values.s_y)/scaley;
+
+	return {
+	    scalex: scalex,
+	    scaley: scaley,
+	    offsetx: offsetx,
+	    offsety: offsety,
+	};
+    },
+
+    controller: {
+	xclass: 'Ext.app.ViewController',
+
+	control: {
+	    'field': {
+		change: function() {
+		    let view = this.getView();
+		    let param = view.getValues();
+		    view.fireEvent("calibrationchanged", param);
+		},
+	    },
+	},
+    },
+
+    items: [
+	{
+	    border: false,
+	    layout: {
+		type: 'vbox',
+		align: 'stretch',
+		pack: 'start',
+	    },
+	    items: [
+		{
+		    xtype: 'displayfield',
+		    value: 'a4',
+		    fieldLabel: 'Start Offset Sx (mm)',
+		    labelWidth: 150,
+		    value: 50,
+		},
+		{
+		    xtype: 'displayfield',
+		    value: 'a4',
+		    fieldLabel: 'Length Dx (mm)',
+		    labelWidth: 150,
+		    value: 100,
+		},
+		{
+		    xtype: 'displayfield',
+		    value: 'a4',
+		    fieldLabel: 'Start Offset Sy (mm)',
+		    labelWidth: 150,
+		    value: 50,
+		},
+		{
+		    xtype: 'displayfield',
+		    value: 'a4',
+		    fieldLabel: 'Length Dy (mm)',
+		    labelWidth: 150,
+		    value: 100,
+		},
+	    ],
+	},
+	{
+	    border: false,
+	    margin: '0 0 0 20',
+	    layout: {
+		type: 'vbox',
+		align: 'stretch',
+		pack: 'start',
+	    },
+	    items: [
+		{
+		    xtype: 'numberfield',
+		    value: 'a4',
+		    name: 's_x',
+		    fieldLabel: 'Meassured Start Offset Sx (mm)',
+		    allowBlank: false,
+		    labelWidth: 200,
+		},
+		{
+		    xtype: 'numberfield',
+		    value: 'a4',
+		    name: 'd_x',
+		    fieldLabel: 'Meassured Length Dx (mm)',
+		    allowBlank: false,
+		    labelWidth: 200,
+		},
+		{
+		    xtype: 'numberfield',
+		    value: 'a4',
+		    name: 's_y',
+		    fieldLabel: 'Meassured Start Offset Sy (mm)',
+		    allowBlank: false,
+		    labelWidth: 200,
+		},
+		{
+		    xtype: 'numberfield',
+		    value: 'a4',
+		    name: 'd_y',
+		    fieldLabel: 'Meassured Length Dy (mm)',
+		    allowBlank: false,
+		    labelWidth: 200,
+		},
+	    ],
+	},
+    ],
+})

docs/lto-barcode/page-layout.js

@@ -0,0 +1,167 @@
+Ext.define('PageLayoutPanel', {
+    extend: 'Ext.panel.Panel',
+    alias: 'widget.pageLayoutPanel',
+
+    layout: {
+	type: 'hbox',
+	align: 'stretch',
+	pack: 'start',
+    },
+
+    getValues: function() {
+	let me = this;
+
+	let values = {};
+
+	Ext.Array.each(me.query('[isFormField]'), function(field) {
+	    if (field.isValid()) {
+		let data = field.getSubmitData();
+		Ext.Object.each(data, function(name, val) {
+		    values[name] = val;
+		});
+	    }
+	});
+
+	let paper_size = values.paper_size || 'a4';
+
+	let param = Ext.apply({}, paper_sizes[paper_size]);
+	if (param === undefined) {
+	    throw `unknown paper size ${paper_size}`;
+	}
+
+	param.paper_size = paper_size;
+
+	Ext.Object.each(values, function(name, val) {
+	    let parsed = parseFloat(val, 10);
+	    param[name] = isNaN(parsed) ? val : parsed;
+	});
+
+	return param;
+    },
+
+    controller: {
+	xclass: 'Ext.app.ViewController',
+
+	control: {
+	    'paperSize': {
+		change: function(field, paper_size) {
+		    let view = this.getView();
+		    let defaults = paper_sizes[paper_size];
+
+		    let names = [
+			'label_width',
+			'label_height',
+			'margin_left',
+			'margin_top',
+			'column_spacing',
+			'row_spacing',
+		    ];
+		    for (i = 0; i < names.length; i++) {
+			let name = names[i];
+			let f = view.down(`field[name=${name}]`);
+			let v = defaults[name];
+			if (v != undefined) {
+			    f.setValue(v);
+			    f.setDisabled(defaults.fixed);
+			} else {
+			    f.setDisabled(false);
+			}
+		    }
+		},
+	    },
+	    'field': {
+		change: function() {
+		    let view = this.getView();
+		    let param = view.getValues();
+		    view.fireEvent("pagechanged", param);
+		},
+	    },
+	},
+    },
+
+    items: [
+	{
+	    border: false,
+	    layout: {
+		type: 'vbox',
+		align: 'stretch',
+		pack: 'start',
+	    },
+	    items: [
+		{
+		    xtype: 'paperSize',
+		    name: 'paper_size',
+		    value: 'a4',
+		    fieldLabel: 'Paper Size',
+		},
+		{
+		    xtype: 'numberfield',
+		    name: 'label_width',
+		    fieldLabel: 'Label width',
+		    minValue: 70,
+		    allowBlank: false,
+		    value: 70,
+		},
+		{
+		    xtype: 'numberfield',
+		    name: 'label_height',
+		    fieldLabel: 'Label height',
+		    minValue: 17,
+		    allowBlank: false,
+		    value: 17,
+		},
+		{
+		    xtype: 'checkbox',
+		    name: 'label_borders',
+		    fieldLabel: 'Label borders',
+		    value: true,
+		    inputValue: true,
+		},
+	    ],
+	},
+	{
+	    border: false,
+	    margin: '0 0 0 10',
+	    layout: {
+		type: 'vbox',
+		align: 'stretch',
+		pack: 'start',
+	    },
+	    items: [
+		{
+		    xtype: 'numberfield',
+		    name: 'margin_left',
+		    fieldLabel: 'Left margin',
+		    minValue: 0,
+		    allowBlank: false,
+		    value: 0,
+		},
+		{
+		    xtype: 'numberfield',
+		    name: 'margin_top',
+		    fieldLabel: 'Top margin',
+		    minValue: 0,
+		    allowBlank: false,
+		    value: 4,
+		},
+		{
+		    xtype: 'numberfield',
+		    name: 'column_spacing',
+		    fieldLabel: 'Column spacing',
+		    minValue: 0,
+		    allowBlank: false,
+		    value: 0,
+		},
+		{
+		    xtype: 'numberfield',
+		    name: 'row_spacing',
+		    fieldLabel: 'Row spacing',
+		    minValue: 0,
+		    allowBlank: false,
+		    value: 0,
+		},
+	    ],
+	},
+    ],
+
+});

docs/lto-barcode/paper-size.js

@@ -0,0 +1,49 @@
+let paper_sizes = {
+    a4: {
+	comment: 'A4 (plain)',
+	page_width: 210,
+	page_height: 297,
+    },
+    letter: {
+	comment: 'Letter (plain)',
+	page_width: 215.9,
+	page_height: 279.4,
+    },
+    avery3420: {
+	fixed: true,
+	comment: 'Avery Zweckform 3420',
+	page_width: 210,
+	page_height: 297,
+	label_width: 70,
+	label_height: 17,
+	margin_left: 0,
+	margin_top: 4,
+	column_spacing: 0,
+	row_spacing: 0,
+    },
+}
+
+function paper_size_combo_data() {
+    let data = [];
+
+    for (let [key, value] of Object.entries(paper_sizes)) {
+	data.push({ value: key, text: value.comment });
+    }
+    return data;
+}
+
+Ext.define('PaperSize', {
+    extend: 'Ext.form.field.ComboBox',
+    alias: 'widget.paperSize',
+
+    editable: false,
+
+    displayField: 'text',
+    valueField: 'value',
+    queryMode: 'local',
+
+    store: {
+	field: ['value', 'text'],
+	data: paper_size_combo_data(),
+    },
+});

docs/lto-barcode/prefix-field.js

@@ -0,0 +1,15 @@
+Ext.define('PrefixField', {
+    extend: 'Ext.form.field.Text',
+    alias: 'widget.prefixfield',
+
+    maxLength: 6,
+    allowBlank: false,
+
+    maskRe: /([A-Za-z]+)$/,
+
+    listeners: {
+	change: function(field) {
+	    field.setValue(field.getValue().toUpperCase());
+	},
+    },
+});

docs/lto-barcode/tape-type.js

@@ -0,0 +1,23 @@
+Ext.define('LtoTapeType', {
+    extend: 'Ext.form.field.ComboBox',
+    alias: 'widget.ltoTapeType',
+
+    editable: false,
+
+    displayField: 'text',
+    valueField: 'value',
+    queryMode: 'local',
+
+    store: {
+	field: ['value', 'text'],
+	data: [
+	    { value: 'L8', text: "LTO-8" },
+	    { value: 'L7', text: "LTO-7" },
+	    { value: 'L6', text: "LTO-6" },
+	    { value: 'L5', text: "LTO-5" },
+	    { value: 'L4', text: "LTO-4" },
+	    { value: 'L3', text: "LTO-3" },
+	    { value: 'CU', text: "Cleaning Unit" },
+	],
+    },
+});

docs/maintenance.rst

@@ -0,0 +1,184 @@
+Maintenance Tasks
+=================
+
+.. _maintenance_pruning:
+
+Pruning
+-------
+
+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.
+
+Prune Simulator
+^^^^^^^^^^^^^^^
+
+You can use the built-in `prune simulator <prune-simulator/index.html>`_
+to explore the effect of different retetion options with various backup
+schedules.
+
+Manual Pruning
+^^^^^^^^^^^^^^
+
+.. image:: images/screenshots/pbs-gui-datastore-content-prune-group.png
+  :target: _images/pbs-gui-datastore-content-prune-group.png
+  :align: right
+  :alt: Prune and garbage collection options
+
+To access pruning functionality for a specific backup group, you can use the
+prune command line option discussed in :ref:`backup-pruning`, or navigate to
+the **Content** tab of the datastore and click the scissors icon in the
+**Actions** column of the relevant backup group.
+
+Prune Schedules
+^^^^^^^^^^^^^^^
+
+To prune on a datastore level, scheduling options can be found under the
+**Prune & GC** tab of the datastore. Here you can set retention settings and
+edit the interval at which pruning takes place.
+
+.. image:: images/screenshots/pbs-gui-datastore-prunegc.png
+  :target: _images/pbs-gui-datastore-prunegc.png
+  :align: right
+  :alt: Prune and garbage collection options
+
+
+Retention Settings Example
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The backup frequency and retention of old backups may depend on how often data
+changes, and how important an older state may be, in a specific work load.
+When backups act as a company's document archive, there may also be legal
+requirements for how long backup snapshots must be kept.
+
+For this example, we assume that you are doing daily backups, have a retention
+period of 10 years, and the period between backups stored gradually grows.
+
+- **keep-last:** ``3`` - even if only daily backups, an admin may want to create
+  an extra one just before or after a big upgrade. Setting keep-last ensures
+  this.
+
+- **keep-hourly:** not set - for daily backups this is not relevant. You cover
+  extra manual backups already, with keep-last.
+
+- **keep-daily:** ``13`` - together with keep-last, which covers at least one
+  day, this ensures that you have at least two weeks of backups.
+
+- **keep-weekly:** ``8`` - ensures that you have at least two full months of
+  weekly backups.
+
+- **keep-monthly:** ``11`` - together with the previous keep settings, this
+  ensures that you have at least a year of monthly backups.
+
+- **keep-yearly:** ``9`` - this is for the long term archive. As you covered the
+  current year with the previous options, you would set this to nine for the
+  remaining ones, giving you a total of at least 10 years of coverage.
+
+We recommend that you use a higher retention period than is minimally required
+by your environment; you can always reduce it if you find it is unnecessarily
+high, but you cannot recreate backup snapshots from the past.
+
+
+.. _maintenance_gc:
+
+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>`.
+
+This functionality can also be accessed in the GUI, by navigating to **Prune &
+GC** from the top panel. From here, you can edit the schedule at which garbage
+collection runs and manually start the operation.
+
+
+.. _maintenance_verification:
+
+Verification
+------------
+
+.. image:: images/screenshots/pbs-gui-datastore-verifyjob-add.png
+  :target: _images/pbs-gui-datastore-verifyjob-add.png
+  :align: right
+  :alt: Adding a verify job
+
+Proxmox Backup offers various verification options to ensure that backup data is
+intact.  Verification is generally carried out through the creation of verify
+jobs. These are scheduled tasks that run verification at a given interval (see
+:ref:`calendar-events`). With these, you can set whether already verified
+snapshots are ignored, as well as set a time period, after which verified jobs
+are checked again. The interface for creating verify jobs can be found under the
+**Verify Jobs** tab of the datastore.
+
+.. Note:: It is recommended that you reverify all backups at least monthly, even
+  if a previous verification was successful. This is becuase physical drives
+  are susceptible to damage over time, which can cause an old, working backup
+  to become corrupted in a process known as `bit rot/data degradation
+  <https://en.wikipedia.org/wiki/Data_degradation>`_. It is good practice to
+  have a regularly recurring (hourly/daily) verification job, which checks new
+  and expired backups, then another weekly/monthly job that will reverify
+  everything. This way, there will be no surprises when it comes to restoring
+  data.
+
+Aside from using verify jobs, you can also run verification manually on entire
+datastores, backup groups, or snapshots. To do this, navigate to the **Content**
+tab of the datastore and either click *Verify All*, or select the *V.* icon from
+the *Actions* column in the table.
+
+.. _maintenance_notification:
+
+Notifications
+-------------
+
+Proxmox Backup Server can send you notification emails about automatically
+scheduled verification, garbage-collection and synchronization tasks results.
+
+By default, notifications are send to the email address configured for the
+`root@pam` user. You can set that user for each datastore.
+
+You can also change the level of notification received per task type, the
+following options are available:
+
+* Always: send a notification for any scheduled task, independent of the
+  outcome
+
+* Errors: send a notification for any scheduled task resulting in an error
+
+* Never: do not send any notification at all

docs/managing-remotes.rst

@@ -0,0 +1,95 @@
+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 in the web interface, from the
+**Sync Jobs** tab of the datastore which you'd like to set one up for, 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 from 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
+
+For setting up sync jobs, the configuring user needs the following permissions:
+
+#. ``Remote.Read`` on the ``/remote/{remote}/{remote-store}`` path
+#. at least ``Datastore.Backup`` on the local target datastore (``/datastore/{store}``)
+
+If the ``remove-vanished`` option is set, ``Datastore.Prune`` is required on
+the local datastore as well. If the ``owner`` option is not set (defaulting to
+``root@pam``) or set to something other than the configuring user,
+``Datastore.Modify`` is required as well.
+
+.. note:: A sync job can only sync backup groups that the configured remote's
+  user/API token can read. If a remote is configured with a user/API token that
+  only has ``Datastore.Backup`` privileges, only the limited set of accessible
+  snapshots owned by that user/API token can be synced.

docs/network-management.rst

@@ -0,0 +1,90 @@
+.. _sysadmin_network_configuration:
+
+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

@@ -26,11 +26,8 @@ update``.
 
 .. FIXME for 7.0: change security update suite to bullseye-security
 
-In addition, you need a package repository from Proxmox to get Proxmox Backup updates.
+In addition, you need a package repository from Proxmox to get Proxmox Backup
-
+updates.
-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.
 
 SecureApt
 ~~~~~~~~~
@@ -72,68 +69,63 @@ Here, the output should be:
 
  f3f6c5a3a67baf38ad178e5ff1ee270c /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
 
-.. comment
+`Proxmox Backup`_ Enterprise Repository
-    `Proxmox Backup`_ Enterprise Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    This will be the default, stable, and recommended repository. It is available for
+This will be the default, stable, and recommended repository. It is available for
-    all `Proxmox Backup`_ subscription users. It contains the most stable packages,
+all `Proxmox Backup`_ subscription users. It contains the most stable packages,
-    and is suitable for production use. The ``pbs-enterprise`` repository is
+and is suitable for production use. The ``pbs-enterprise`` repository is
-    enabled by default:
+enabled by default:
 
-    .. note:: During the Proxmox Backup beta phase only one repository (pbstest)
+.. code-block:: sources.list
-     will be available.
+  :caption: File: ``/etc/apt/sources.list.d/pbs-enterprise.list``
 
-    .. code-block:: sources.list
+  deb https://enterprise.proxmox.com/debian/pbs buster pbs-enterprise
-      :caption: File: ``/etc/apt/sources.list.d/pbs-enterprise.list``
-
-      deb https://enterprise.proxmox.com/debian/pbs buster pbs-enterprise
 
 
-    To never miss important security fixes, the superuser (``root@pam`` user) is
+To never miss important security fixes, the superuser (``root@pam`` user) is
-    notified via email about new packages as soon as they are available. The
+notified via email about new packages as soon as they are available. The
-    change-log and details of each package can be viewed in the GUI (if available).
+change-log and details of each package can be viewed in the GUI (if available).
 
-    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. More information regarding subscription levels and pricing can be
+repository. More information regarding subscription levels and pricing can be
-    found at https://www.proxmox.com/en/proxmox-backup/pricing.
+found at https://www.proxmox.com/en/proxmox-backup-server/pricing
 
-    .. note:: You can disable this repository by commenting out the above
+.. note:: You can disable this repository by commenting out the above line
-      line using a `#` (at the start of the line). This prevents error
+ using a `#` (at the start of the line). This prevents error messages if you do
-      messages if you do not have a subscription key. Please configure the
+ not have a subscription key. Please configure the ``pbs-no-subscription``
-      ``pbs-no-subscription`` repository in that case.
+ 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. It is not recommended to use it on production servers, because 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/pbs 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`_ Beta Repository
+`Proxmox Backup`_ Test Repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-During the public beta, there is a repository called ``pbstest``. This one
+This repository contains the latest packages and is heavily used by developers
-contains the latest packages and is heavily used by developers to test new
+to test new features.
-features.
 
 .. .. warning:: the ``pbstest`` repository should (as the name implies)
   only be used to test new features or bug fixes.
@@ -145,7 +137,3 @@ You can access this repository by adding the following line to
   :caption: sources.list entry for ``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/pmtx/description.rst

@@ -0,0 +1,6 @@
+Description
+^^^^^^^^^^^
+
+The ``pmtx`` command controls SCSI media changer devices (tape
+autoloader).
+

docs/pmtx/man1.rst

@@ -0,0 +1,28 @@
+==========================
+pmtx
+==========================
+
+.. include:: ../epilog.rst
+
+-------------------------------------------------------------
+Control SCSI media changer devices (tape autoloaders)
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 1
+
+
+Synopsis
+==========
+
+.. include:: synopsis.rst
+
+Description
+============
+
+.. include:: description.rst
+
+
+.. include:: ../pbs-copyright.rst
+

docs/proxmox-backup-client/man1.rst

@@ -5,7 +5,7 @@ proxmox-backup-client
 .. include:: ../epilog.rst
 
 -------------------------------------------------------------
-Command line toot for Backup and Restore
+Command line tool for Backup and Restore
 -------------------------------------------------------------
 
 :Author: |AUTHOR|

docs/prune-simulator/documentation.html

@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html>
+<head>
+<style>
+    /* similar to sphinx alabaster theme ones */
+    body {
+        max-width: 90ch;
+        margin-left: 2ch;
+        margin-right: 2ch;
+        line-height: 1.4em;
+        /* avoid the very high contrast of black on white, tone it down a bit */
+        color: #3E4349;
+        hyphens: auto;
+        text-align: left;
+        font-family: 'Open Sans', sans-serif;
+        font-size: 17px;
+    }
+    h1, h2, h3 {
+        font-family: Lato, sans-serif;
+        font-size: 150%;
+        line-height:1.2
+    }
+    tt, code {
+        background-color: #ecf0f3;
+        color: #222;
+    }
+    pre, tt, code {
+        font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+        font-size: 0.9em;
+    }
+    div.note {
+        background-color: #EEE;
+        border: 1px solid #CCC;
+        margin: 10px 0;
+        padding: 0px 20px;
+    }
+    p.note-title {
+        font-weight: bolder;
+        padding: 0;
+        margin: 10px 0 0 0;
+    }
+    div.note > p.last {
+        margin: 5px 0 10px 0;
+    }
+</style>
+</head>
+<body>
+<p>A simulator to experiment with different backup schedules and prune
+options.</p>
+
+<h3>Schedule</h3>
+<p>Select weekdays with the combobox and input hour and minute
+specification separated by a colon, i.e. <code>HOUR:MINUTE</code>. Each of
+<code>HOUR</code> and <code>MINUTE</code> can be either a single value or
+one of the following:</p>
+<ul class="simple">
+<li>a comma-separated list: e.g., <code>01,02,03</code></li>
+<li>a range: e.g., <code>01..10</code></li>
+<li>a repetition: e.g, <code>05/10</code> (means starting at <code>5</code> every <code>10</code>)</li>
+<li>a combination of the above: e.g., <code>01,05..10,12/02</code></li>
+<li>a <code>*</code> for every possible value</li>
+</ul>
+
+<h3>Pruning</h3>
+<p>Prune lets you systematically delete older backups, retaining backups for
+the last given number of time intervals. The following retention options are
+available:</p>
+<dl class="docutils">
+<dt><code class="docutils literal notranslate"><span class="pre">keep-last</span> <span class="pre">&lt;N&gt;</span></code></dt>
+<dd>Keep the last <code class="docutils literal notranslate"><span class="pre">&lt;N&gt;</span></code> backup snapshots.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">keep-hourly</span> <span class="pre">&lt;N&gt;</span></code></dt>
+<dd>Keep backups for the last <code class="docutils literal notranslate"><span class="pre">&lt;N&gt;</span></code> hours. If there is more than one
+backup for a single hour, only the latest is kept.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">keep-daily</span> <span class="pre">&lt;N&gt;</span></code></dt>
+<dd>Keep backups for the last <code class="docutils literal notranslate"><span class="pre">&lt;N&gt;</span></code> days. If there is more than one
+backup for a single day, only the latest is kept.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">keep-weekly</span> <span class="pre">&lt;N&gt;</span></code></dt>
+<dd>Keep backups for the last <code class="docutils literal notranslate"><span class="pre">&lt;N&gt;</span></code> weeks. If there is more than one
+backup for a single week, only the latest is kept.
+<div class="last admonition note">
+<p class="note-title">Note:</p>
+<p class="last">Weeks start on Monday and end on Sunday. The software
+uses the <a class="reference external" href="https://en.wikipedia.org/wiki/ISO_week_date">ISO week date</a> system and handles weeks at
+the end of the year correctly.</p>
+</div>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">keep-monthly</span> <span class="pre">&lt;N&gt;</span></code></dt>
+<dd>Keep backups for the last <code class="docutils literal notranslate"><span class="pre">&lt;N&gt;</span></code> months. If there is more than one
+backup for a single month, only the latest is kept.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">keep-yearly</span> <span class="pre">&lt;N&gt;</span></code></dt>
+<dd>Keep backups for the last <code class="docutils literal notranslate"><span class="pre">&lt;N&gt;</span></code> years. If there is more than one
+backup for a single year, only the latest is kept.</dd>
+</dl>
+<p>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.</p>
+<p>For example, in a week covered by <code>keep-weekly</code>, one backup is
+kept while all others are removed; <code>keep-monthly</code> then does not
+consider backups from that week anymore, even if part of the week is part of
+an earlier month.</p>
+</body>
+</html>

docs/prune-simulator/index.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
+    <title>PBS Prune Simulator</title>
+
+    <link rel="stylesheet" type="text/css" href="extjs/theme-crisp/resources/theme-crisp-all.css">
+    <style>
+        .cal {
+            margin: 5px;
+        }
+        .cal-day {
+            vertical-align: top;
+            width: 150px;
+            height: 75px; /* this is like min-height when used in tables */
+            border: #939393 1px solid;
+            color: #454545;
+        }
+        .cal-day-date {
+            border-bottom: #444 1px solid;
+            color: #000;
+        }
+        .strikethrough {
+            text-decoration: line-through;
+        }
+        .black {
+            color: #000;
+        }
+        .sun {
+            background-color: #ededed;
+        }
+        .first-of-month {
+            border-right: dashed black 4px;
+        }
+        .clear-trigger {
+            background-image: url(./clear-trigger.png);
+        }
+    </style>
+
+    <script type="text/javascript" src="extjs/ext-all.js"></script>
+    <script type="text/javascript" src="prune-simulator.js"></script>
+</head>
+<body></body>
+</html>

docs/prune-simulator/prune-simulator.js

@@ -0,0 +1,788 @@
+// FIXME: HACK! Makes scrolling in number spinner work again. fixed in ExtJS >= 6.1
+if (Ext.isFirefox) {
+    Ext.$eventNameMap.DOMMouseScroll = 'DOMMouseScroll';
+}
+
+Ext.onReady(function() {
+    const NOW = new Date();
+    const COLORS = {
+	'keep-last': 'orange',
+	'keep-hourly': 'purple',
+	'keep-daily': 'yellow',
+	'keep-weekly': 'green',
+	'keep-monthly': 'blue',
+	'keep-yearly': 'red',
+	'all zero': 'white',
+    };
+    const TEXT_COLORS = {
+	'keep-last': 'black',
+	'keep-hourly': 'white',
+	'keep-daily': 'black',
+	'keep-weekly': 'white',
+	'keep-monthly': 'white',
+	'keep-yearly': 'white',
+	'all zero': 'black',
+    };
+
+    Ext.define('PBS.prunesimulator.Documentation', {
+	extend: 'Ext.Panel',
+	alias: 'widget.prunesimulatorDocumentation',
+
+	html: '<iframe style="width:100%;height:100%;border:0px;" src="./documentation.html"/>',
+    });
+
+    Ext.define('PBS.prunesimulator.CalendarEvent', {
+	extend: 'Ext.form.field.ComboBox',
+	alias: 'widget.prunesimulatorCalendarEvent',
+
+	editable: true,
+
+	displayField: 'text',
+	valueField: 'value',
+	queryMode: 'local',
+
+	store: {
+	    field: ['value', 'text'],
+	    data: [
+		{ value: '0/2:00', text: "Every two hours" },
+		{ value: '0/6:00', text: "Every six hours" },
+		{ value: '2,22:30', text: "At 02:30 and 22:30" },
+		{ value: '00:00', text: "At 00:00" },
+		{ value: '08..17:00/30', text: "From 08:00 to 17:30 every 30 minutes" },
+		{ value: 'HOUR:MINUTE', text: "Custom schedule" },
+	    ],
+	},
+
+	tpl: [
+	    '<ul class="x-list-plain"><tpl for=".">',
+	    '<li role="option" class="x-boundlist-item">{text}</li>',
+	    '</tpl></ul>',
+	],
+
+	displayTpl: [
+	    '<tpl for=".">',
+	    '{value}',
+	    '</tpl>',
+	],
+    });
+
+    Ext.define('PBS.prunesimulator.DayOfWeekSelector', {
+	extend: 'Ext.form.field.ComboBox',
+	alias: 'widget.prunesimulatorDayOfWeekSelector',
+
+	editable: false,
+
+	displayField: 'text',
+	valueField: 'value',
+	queryMode: 'local',
+
+	store: {
+	    field: ['value', 'text'],
+	    data: [
+		{ value: 'mon', text: Ext.util.Format.htmlDecode(Ext.Date.dayNames[1]) },
+		{ value: 'tue', text: Ext.util.Format.htmlDecode(Ext.Date.dayNames[2]) },
+		{ value: 'wed', text: Ext.util.Format.htmlDecode(Ext.Date.dayNames[3]) },
+		{ value: 'thu', text: Ext.util.Format.htmlDecode(Ext.Date.dayNames[4]) },
+		{ value: 'fri', text: Ext.util.Format.htmlDecode(Ext.Date.dayNames[5]) },
+		{ value: 'sat', text: Ext.util.Format.htmlDecode(Ext.Date.dayNames[6]) },
+		{ value: 'sun', text: Ext.util.Format.htmlDecode(Ext.Date.dayNames[0]) },
+	    ],
+	},
+    });
+
+    Ext.define('pbs-prune-list', {
+	extend: 'Ext.data.Model',
+	fields: [
+	    {
+		name: 'backuptime',
+		type: 'date',
+		dateFormat: 'timestamp',
+	    },
+	    {
+		name: 'mark',
+		type: 'string',
+	    },
+	    {
+		name: 'keepName',
+		type: 'string',
+	    },
+	],
+    });
+
+    Ext.define('PBS.prunesimulator.PruneList', {
+	extend: 'Ext.panel.Panel',
+	alias: 'widget.prunesimulatorPruneList',
+
+	initComponent: function() {
+	    let me = this;
+
+	    if (!me.store) {
+		throw "no store specified";
+	    }
+
+	    me.items = [
+		{
+		    xtype: 'grid',
+		    store: me.store,
+		    border: false,
+		    columns: [
+			{
+			    header: 'Backup Time',
+			    dataIndex: 'backuptime',
+			    renderer: function(value, metaData, record) {
+				let text = Ext.Date.format(value, 'Y-m-d H:i:s');
+				if (record.data.mark === 'keep') {
+				    if (me.useColors) {
+					let bgColor = COLORS[record.data.keepName];
+					let textColor = TEXT_COLORS[record.data.keepName];
+					return '<div style="background-color: ' + bgColor + '; ' +
+							    'color: ' + textColor + ';">' + text + '</div>';
+				    } else {
+					return text;
+				    }
+				} else {
+				    return '<div style="text-decoration: line-through;">' + text + '</div>';
+				}
+			    },
+			    flex: 1,
+			    sortable: false,
+			},
+			{
+			    header: 'Keep (reason)',
+			    dataIndex: 'mark',
+			    renderer: function(value, metaData, record) {
+				if (record.data.mark === 'keep') {
+				    if (record.data.keepCount) {
+					return 'keep (' + record.data.keepName +
+					       ': ' + record.data.keepCount + ')';
+				    } else {
+					return 'keep (' + record.data.keepName + ')';
+				    }
+				} else {
+				    return value;
+				}
+			    },
+			    width: 200,
+			    sortable: false,
+			},
+		    ],
+		},
+	    ];
+
+	    me.callParent();
+	},
+    });
+
+    Ext.define('PBS.prunesimulator.WeekTable', {
+	extend: 'Ext.panel.Panel',
+	alias: 'widget.prunesimulatorWeekTable',
+
+	reload: function() {
+	    let me = this;
+	    let backups = me.store.data.items;
+
+	    let html = '<table class="cal">';
+
+	    let now = new Date(NOW.getTime());
+	    let skip = 7 - parseInt(Ext.Date.format(now, 'N'), 10);
+	    let tableStartDate = Ext.Date.add(now, Ext.Date.DAY, skip);
+
+	    let bIndex = 0;
+
+	    for (let i = 0; bIndex < backups.length; i++) {
+		html += '<tr>';
+
+		for (let j = 0; j < 7; j++) {
+		    let date = Ext.Date.subtract(tableStartDate, Ext.Date.DAY, j + 7 * i);
+		    let currentDay = Ext.Date.format(date, 'd/m/Y');
+
+		    let dayOfWeekCls = Ext.Date.format(date, 'D').toLowerCase();
+		    let firstOfMonthCls = Ext.Date.format(date, 'd') === '01'
+		        ? 'first-of-month'
+		        : '';
+		    html += `<td class="cal-day ${dayOfWeekCls} ${firstOfMonthCls}">`;
+
+		    const isBackupOnDay = function(backup, day) {
+			return backup && Ext.Date.format(backup.data.backuptime, 'd/m/Y') === day;
+		    };
+
+		    let backup = backups[bIndex];
+
+		    html += '<table><tr>';
+		    html += `<th class="cal-day-date">${Ext.Date.format(date, 'D, d M Y')}</th>`;
+
+		    while (isBackupOnDay(backup, currentDay)) {
+			html += '<tr><td>';
+
+			let text = Ext.Date.format(backup.data.backuptime, 'H:i');
+			if (backup.data.mark === 'remove') {
+			    html += `<span class="strikethrough">${text}</span>`;
+			} else {
+			    if (backup.data.keepCount) {
+				text += ` (${backup.data.keepName} ${backup.data.keepCount})`;
+			    } else {
+				text += ` (${backup.data.keepName})`;
+			    }
+			    if (me.useColors) {
+				let bgColor = COLORS[backup.data.keepName];
+				let textColor = TEXT_COLORS[backup.data.keepName];
+				html += `<span style="background-color: ${bgColor};
+				    color: ${textColor};">${text}</span>`;
+			    } else {
+				html += `<span class="black">${text}</span>`;
+			    }
+			}
+			html += '</td></tr>';
+			backup = backups[++bIndex];
+		    }
+		    html += '</table>';
+		    html += '</div>';
+		    html += '</td>';
+		}
+
+		html += '</tr>';
+	    }
+
+	    me.setHtml(html);
+	},
+
+	initComponent: function() {
+	    let me = this;
+
+	    if (!me.store) {
+		throw "no store specified";
+	    }
+
+	    let reload = function() {
+		me.reload();
+	    };
+
+	    me.store.on("datachanged", reload);
+
+	    me.callParent();
+
+	    me.reload();
+	},
+    });
+
+    Ext.define('PBS.PruneSimulatorKeepInput', {
+	extend: 'Ext.form.field.Number',
+	alias: 'widget.prunesimulatorKeepInput',
+
+	allowBlank: true,
+	fieldGroup: 'keep',
+	minValue: 1,
+
+	listeners: {
+	    afterrender: function(field) {
+		this.triggers.clear.setVisible(field.value !== null);
+	    },
+	    change: function(field, newValue, oldValue) {
+		this.triggers.clear.setVisible(newValue !== null);
+	    },
+	},
+	triggers: {
+	    clear: {
+		cls: 'clear-trigger',
+		weight: -1,
+		handler: function() {
+		    this.triggers.clear.setVisible(false);
+		    this.setValue(null);
+		},
+	    },
+	},
+    });
+
+    Ext.define('PBS.PruneSimulatorPanel', {
+	extend: 'Ext.panel.Panel',
+	alias: 'widget.prunesimulatorPanel',
+
+	viewModel: {
+	},
+
+	getValues: function() {
+	    let me = this;
+
+	    let values = {};
+
+	    Ext.Array.each(me.query('[isFormField]'), function(field) {
+		let data = field.getSubmitData();
+		Ext.Object.each(data, function(name, val) {
+		    values[name] = val;
+		});
+	    });
+
+	    return values;
+	},
+
+	controller: {
+	    xclass: 'Ext.app.ViewController',
+
+	    init: function(view) {
+		this.reloadFull(); // initial load
+		this.switchColor(true);
+	    },
+
+	    control: {
+		'field[fieldGroup=keep]': { change: 'reloadPrune' },
+	    },
+
+	    reloadFull: function() {
+		let me = this;
+		let view = me.getView();
+
+		let params = view.getValues();
+
+		let [hourSpec, minuteSpec] = params['schedule-time'].split(':');
+
+		if (!hourSpec || !minuteSpec) {
+		    Ext.Msg.alert('Error', 'Invalid schedule');
+		    return;
+		}
+
+		let matchTimeSpec = function(timeSpec, rangeMin, rangeMax) {
+		    let specValues = timeSpec.split(',');
+		    let matches = {};
+
+		    let assertValid = function(value) {
+			let num = Number(value);
+			if (isNaN(num)) {
+			    throw value + " is not an integer";
+			} else if (value < rangeMin || value > rangeMax) {
+			    throw "number '" + value + "' is not in the range '" + rangeMin + ".." + rangeMax + "'";
+			}
+			return num;
+		    };
+
+		    specValues.forEach(function(value) {
+			if (value.includes('..')) {
+			    let [start, end] = value.split('..');
+			    start = assertValid(start);
+			    end = assertValid(end);
+			    if (start > end) {
+				throw "interval start is bigger then interval end '" + start + " > " + end + "'";
+			    }
+			    for (let i = start; i <= end; i++) {
+				matches[i] = 1;
+			    }
+			} else if (value.includes('/')) {
+			    let [start, step] = value.split('/');
+			    start = assertValid(start);
+			    step = assertValid(step);
+			    for (let i = start; i <= rangeMax; i += step) {
+				matches[i] = 1;
+			    }
+			} else if (value === '*') {
+			    for (let i = rangeMin; i <= rangeMax; i++) {
+				matches[i] = 1;
+			    }
+			} else {
+			    value = assertValid(value);
+			    matches[value] = 1;
+			}
+		    });
+
+		    return Object.keys(matches);
+		};
+
+		let hours, minutes;
+
+		try {
+		    hours = matchTimeSpec(hourSpec, 0, 23);
+		    minutes = matchTimeSpec(minuteSpec, 0, 59);
+		} catch (err) {
+		    Ext.Msg.alert('Error', err);
+		    return;
+		}
+
+		let backups = me.populateFromSchedule(
+		    params['schedule-weekdays'],
+		    hours,
+		    minutes,
+		    params.numberOfWeeks,
+		);
+
+		me.pruneSelect(backups, params);
+
+		view.pruneStore.setData(backups);
+	    },
+
+	    reloadPrune: function() {
+		let me = this;
+		let view = me.getView();
+
+		let params = view.getValues();
+
+		let backups = [];
+		view.pruneStore.getData().items.forEach(function(item) {
+		    backups.push({
+			backuptime: item.data.backuptime,
+		    });
+		});
+
+		me.pruneSelect(backups, params);
+
+		view.pruneStore.setData(backups);
+	    },
+
+	    // backups are sorted descending by date
+	    populateFromSchedule: function(weekdays, hours, minutes, weekCount) {
+		let weekdayFlags = [
+		    weekdays.includes('sun'),
+		    weekdays.includes('mon'),
+		    weekdays.includes('tue'),
+		    weekdays.includes('wed'),
+		    weekdays.includes('thu'),
+		    weekdays.includes('fri'),
+		    weekdays.includes('sat'),
+		];
+
+		let todaysDate = new Date(NOW.getTime());
+
+		let timesOnSingleDay = [];
+
+		hours.forEach(function(hour) {
+		    minutes.forEach(function(minute) {
+			todaysDate.setHours(hour);
+			todaysDate.setMinutes(minute);
+			timesOnSingleDay.push(todaysDate.getTime());
+		    });
+		});
+
+		// sort recent times first, backups array below is ordered now -> past
+		timesOnSingleDay.sort((a, b) => b - a);
+
+		let backups = [];
+
+		for (let i = 0; i < 7 * weekCount; i++) {
+		    let daysDate = Ext.Date.subtract(todaysDate, Ext.Date.DAY, i);
+		    let weekday = parseInt(Ext.Date.format(daysDate, 'w'), 10);
+		    if (weekdayFlags[weekday]) {
+			timesOnSingleDay.forEach(function(time) {
+			    backups.push({
+				backuptime: Ext.Date.subtract(new Date(time), Ext.Date.DAY, i),
+			    });
+			});
+		    }
+		}
+
+		return backups;
+	    },
+
+	    pruneMark: function(backups, keepCount, keepName, idFunc) {
+		if (!keepCount) {
+		    return;
+		}
+
+		let alreadyIncluded = {};
+		let newlyIncluded = {};
+		let newlyIncludedCount = 0;
+
+		let finished = false;
+
+		backups.forEach(function(backup) {
+		    let mark = backup.mark;
+		    if (mark && mark === 'keep') {
+			let id = idFunc(backup);
+			alreadyIncluded[id] = true;
+		    }
+		});
+
+		backups.forEach(function(backup) {
+		    let mark = backup.mark;
+		    let id = idFunc(backup);
+
+		    if (finished || alreadyIncluded[id] || mark) {
+			return;
+		    }
+
+		    if (!newlyIncluded[id]) {
+			if (newlyIncludedCount >= keepCount) {
+			    finished = true;
+			    return;
+			}
+			newlyIncluded[id] = true;
+			newlyIncludedCount++;
+			backup.mark = 'keep';
+			backup.keepName = keepName;
+			backup.keepCount = newlyIncludedCount;
+		    } else {
+			backup.mark = 'remove';
+		    }
+		});
+	    },
+
+	    // backups need to be sorted descending by date
+	    pruneSelect: function(backups, keepParams) {
+		let me = this;
+
+		if (Number(keepParams['keep-last']) +
+		    Number(keepParams['keep-hourly']) +
+		    Number(keepParams['keep-daily']) +
+		    Number(keepParams['keep-weekly']) +
+		    Number(keepParams['keep-monthly']) +
+		    Number(keepParams['keep-yearly']) === 0) {
+		    backups.forEach(function(backup) {
+			backup.mark = 'keep';
+			backup.keepName = 'keep-all';
+		    });
+
+		    return;
+		}
+
+		me.pruneMark(backups, keepParams['keep-last'], 'keep-last', function(backup) {
+		    return backup.backuptime;
+		});
+		me.pruneMark(backups, keepParams['keep-hourly'], 'keep-hourly', function(backup) {
+		    return Ext.Date.format(backup.backuptime, 'H/d/m/Y');
+		});
+		me.pruneMark(backups, keepParams['keep-daily'], 'keep-daily', function(backup) {
+		    return Ext.Date.format(backup.backuptime, 'd/m/Y');
+		});
+		me.pruneMark(backups, keepParams['keep-weekly'], 'keep-weekly', function(backup) {
+		    // ISO-8601 week and week-based year
+		    return Ext.Date.format(backup.backuptime, 'W/o');
+		});
+		me.pruneMark(backups, keepParams['keep-monthly'], 'keep-monthly', function(backup) {
+		    return Ext.Date.format(backup.backuptime, 'm/Y');
+		});
+		me.pruneMark(backups, keepParams['keep-yearly'], 'keep-yearly', function(backup) {
+		    return Ext.Date.format(backup.backuptime, 'Y');
+		});
+
+		backups.forEach(function(backup) {
+		    backup.mark = backup.mark || 'remove';
+		});
+	    },
+
+	    toggleColors: function(checkbox, checked) {
+		this.switchColor(checked);
+	    },
+
+	    switchColor: function(useColors) {
+		let me = this;
+		let view = me.getView();
+
+		const getStyle = name =>
+		    `background-color: ${COLORS[name]}; color: ${TEXT_COLORS[name]};`;
+
+		for (const field of view.query('[isFormField]')) {
+		    if (field.fieldGroup !== 'keep') {
+			continue;
+		    }
+		    if (useColors) {
+		    field.setFieldStyle(getStyle(field.name));
+		    } else {
+			field.setFieldStyle('background-color: white; color: #444;');
+		    }
+		}
+
+		me.lookup('weekTable').useColors = useColors;
+		me.lookup('pruneList').useColors = useColors;
+
+		me.reloadPrune();
+	    },
+	},
+
+	keepItems: [
+	    {
+		xtype: 'prunesimulatorKeepInput',
+		name: 'keep-last',
+		fieldLabel: 'keep-last',
+		value: 4,
+	    },
+	    {
+		xtype: 'prunesimulatorKeepInput',
+		name: 'keep-hourly',
+		fieldLabel: 'keep-hourly',
+	    },
+	    {
+		xtype: 'prunesimulatorKeepInput',
+		name: 'keep-daily',
+		fieldLabel: 'keep-daily',
+		value: 5,
+	    },
+	    {
+		xtype: 'prunesimulatorKeepInput',
+		name: 'keep-weekly',
+		fieldLabel: 'keep-weekly',
+		value: 2,
+	    },
+	    {
+		xtype: 'prunesimulatorKeepInput',
+		name: 'keep-monthly',
+		fieldLabel: 'keep-monthly',
+	    },
+	    {
+		xtype: 'prunesimulatorKeepInput',
+		name: 'keep-yearly',
+		fieldLabel: 'keep-yearly',
+	    },
+	],
+
+	initComponent: function() {
+	    var me = this;
+
+	    me.pruneStore = Ext.create('Ext.data.Store', {
+		model: 'pbs-prune-list',
+		sorters: { property: 'backuptime', direction: 'DESC' },
+	    });
+
+	    me.items = [
+		{
+		    xtype: 'panel',
+		    layout: {
+			type: 'hbox',
+			align: 'stretch',
+		    },
+		    border: false,
+		    items: [
+			{
+			    title: 'View',
+			    layout: 'anchor',
+			    flex: 1,
+			    border: false,
+			    bodyPadding: 10,
+			    items: [
+				{
+				    xtype: 'checkbox',
+				    name: 'showCalendar',
+				    reference: 'showCalendar',
+				    fieldLabel: 'Show Calendar:',
+				    checked: true,
+				},
+				{
+				    xtype: 'checkbox',
+				    name: 'showColors',
+				    reference: 'showColors',
+				    fieldLabel: 'Show Colors:',
+				    checked: true,
+				    handler: 'toggleColors',
+				},
+			    ],
+			},
+			{ xtype: "panel", width: 1, border: 1 },
+			{
+			    xtype: 'form',
+			    layout: 'anchor',
+			    flex: 1,
+			    border: false,
+			    title: 'Simulated Backup Schedule',
+			    defaults: {
+				labelWidth: 120,
+			    },
+			    bodyPadding: 10,
+			    items: [
+				{
+				    xtype: 'prunesimulatorDayOfWeekSelector',
+				    name: 'schedule-weekdays',
+				    fieldLabel: 'Day of week',
+				    value: ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'],
+				    allowBlank: false,
+				    multiSelect: true,
+				    padding: '0 0 0 10',
+				},
+				{
+				    xtype: 'prunesimulatorCalendarEvent',
+				    name: 'schedule-time',
+				    allowBlank: false,
+				    value: '0/6:00',
+				    fieldLabel: 'Backup schedule',
+				    padding: '0 0 0 10',
+				},
+				{
+				    xtype: 'numberfield',
+				    name: 'numberOfWeeks',
+				    allowBlank: false,
+				    fieldLabel: 'Number of weeks',
+				    minValue: 1,
+				    value: 15,
+				    maxValue: 260, // five years
+				    padding: '0 0 0 10',
+				},
+				{
+				    xtype: 'button',
+				    name: 'schedule-button',
+				    text: 'Update Schedule',
+				    formBind: true,
+				    handler: 'reloadFull',
+				},
+			    ],
+			},
+		    ],
+		},
+		{
+		    xtype: 'panel',
+		    layout: {
+			type: 'hbox',
+			align: 'stretch',
+		    },
+		    flex: 1,
+		    border: false,
+		    items: [
+			{
+			    layout: 'anchor',
+			    title: 'Prune Options',
+			    border: false,
+			    bodyPadding: 10,
+			    scrollable: true,
+			    items: me.keepItems,
+			    flex: 1,
+			},
+			{ xtype: "panel", width: 1, border: 1 },
+			{
+			    layout: 'fit',
+			    title: 'Backups',
+			    border: false,
+			    xtype: 'prunesimulatorPruneList',
+			    store: me.pruneStore,
+			    reference: 'pruneList',
+			    flex: 1,
+			},
+		    ],
+		},
+		{
+		    layout: 'anchor',
+		    title: 'Calendar',
+		    autoScroll: true,
+		    flex: 2,
+		    xtype: 'prunesimulatorWeekTable',
+		    reference: 'weekTable',
+		    store: me.pruneStore,
+		    bind: {
+			hidden: '{!showCalendar.checked}',
+		    },
+		},
+	    ];
+
+	    me.callParent();
+	},
+    });
+
+    Ext.create('Ext.container.Viewport', {
+	layout: 'border',
+	renderTo: Ext.getBody(),
+	items: [
+	    {
+		xtype: 'prunesimulatorPanel',
+		title: 'Proxmox Backup Server - Prune Simulator',
+		region: 'west',
+		layout: {
+		    type: 'vbox',
+		    align: 'stretch',
+		    pack: 'start',
+		},
+		flex: 3,
+		maxWidth: 1090,
+	    },
+	    {
+		xtype: 'prunesimulatorDocumentation',
+		title: 'Usage',
+		border: false,
+		flex: 2,
+		region: 'center',
+	    },
+	],
+    });
+});
+

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

@@ -47,7 +47,7 @@ by running:
 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 possible to pass the ``--exclude`` parameter multiple times, in order to
 match more than one pattern. This allows you to use more complex
 file exclusion/inclusion behavior. However, it is recommended to use

docs/storage.rst

@@ -0,0 +1,251 @@
+Storage
+=======
+
+.. _storage_disk_management:
+
+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 under ``/mnt/datastore/zpool1``:
+
+.. 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-content.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.
+
+
+.. _storage_datastore_create:
+
+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 interface, by clicking **Add
+Datastore** in the side menu, under the **Datastore** section. In the setup
+window:
+
+* *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`).
+* *Comment* can be used to add some contextual information to the datastore.
+
+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,3 +1,5 @@
+.. _sysadmin_host_administration:
+
 Host System Administration
 ==========================
 

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/tape-backup.rst

@@ -0,0 +1,732 @@
+Tape Backup
+===========
+
+Proxmox tape backup provides an easy way to store datastore content
+onto magnetic tapes. This increases data safety because you get:
+
+- an additional copy of the data
+- to a different media type (tape)
+- to an additional location (you can move tapes offsite)
+
+In most restore jobs, only data from the last backup job is restored.
+Restore requests further decline the older the data
+gets. Considering this, tape backup may also help to reduce disk
+usage, because you can safely remove data from disk once archived on
+tape. This is especially true if you need to keep data for several
+years.
+
+Tape backups do not provide random access to the stored data. Instead,
+you need to restore the data to disk before you can access it
+again. Also, if you store your tapes offsite (using some kind of tape
+vaulting service), you need to bring them onsite before you can do any
+restore. So please consider that restores from tapes can take much
+longer than restores from disk.
+
+
+Tape Technology Primer
+----------------------
+
+.. _Linear Tape Open: https://en.wikipedia.org/wiki/Linear_Tape-Open
+
+As of 2021, the only broadly available tape technology standard is
+`Linear Tape Open`_, and different vendors offers LTO Ultrium tape
+drives, autoloaders and LTO tape cartridges.
+
+There are a few vendors offering proprietary drives with
+slight advantages in performance and capacity, but they have
+significant disadvantages:
+
+- proprietary (single vendor)
+- a much higher purchase cost
+
+So we currently do not test such drives.
+
+In general, LTO tapes offer the following advantages:
+
+- Durable (30 years)
+- High Capacity (12 TB)
+- Relatively low cost per TB
+- Cold Media
+- Movable (storable inside vault)
+- Multiple vendors (for both media and drives)
+- Build in AES-CGM Encryption engine
+
+Please note that `Proxmox Backup Server` already stores compressed
+data, so we do not need/use the tape compression feature.
+
+
+Supported Hardware
+------------------
+
+Proxmox Backup Server supports `Linear Tape Open`_ genertion 4 (LTO4)
+or later. In general, all SCSI2 tape drives supported by the Linux
+kernel should work, but feature like hardware encryptions needs LTO4
+or later.
+
+Tape changer support is done using the Linux 'mtx' command line
+tool. So any changer device supported by that tool should work.
+
+
+Drive Performance
+~~~~~~~~~~~~~~~~~
+
+Current LTO-8 tapes provide read/write speeds up to 360MB/s. This means,
+that it still takes a minimum of 9 hours to completely write or
+read a single tape (even at maximum speed).
+
+The only way to speed up that data rate is to use more than one
+drive. That way you can run several backup jobs in parallel, or run
+restore jobs while the other dives are used for backups.
+
+Also consider that you need to read data first from your datastore
+(disk). But a single spinning disk is unable to deliver data at this
+rate. We measured a maximum rate of about 60MB/s to 100MB/s in practice,
+so it takes 33 hours to read 12TB to fill up an LTO-8 tape. If you want
+to run your tape at full speed, please make sure that the source
+datastore is able to deliver that performance (e.g, by using SSDs).
+
+
+Terminology
+-----------
+
+:Tape Labels: are used to uniquely indentify a tape. You normally use
+   some sticky paper labels and apply them on the front of the
+   cartridge. We additionally store the label text magnetically on the
+   tape (first file on tape).
+
+.. _Code 39: https://en.wikipedia.org/wiki/Code_39
+
+.. _LTO Ultrium Cartridge Label Specification: https://www.ibm.com/support/pages/ibm-lto-ultrium-cartridge-label-specification
+
+.. _LTO Barcode Generator: lto-barcode/index.html
+
+:Barcodes: are a special form of tape labels, which are electronically
+   readable. Most LTO tape robots use an 8 character string encoded as
+   `Code 39`_, as definded in the `LTO Ultrium Cartridge Label
+   Specification`_.
+
+   You can either buy such barcode labels from your cartridge vendor,
+   or print them yourself. You can use our `LTO Barcode Generator`_ App
+   for that.
+
+.. Note:: Physical labels and the associated adhesive shall have an
+   environmental performance to match or exceed the environmental
+   specifications of the cartridge to which it is applied.
+
+:Media Pools: A media pool is a logical container for tapes. A backup
+   job targets one media pool, so a job only uses tapes from that
+   pool. The pool additionally defines how long a backup job can
+   append data to tapes (allocation policy) and how long you want to
+   keep the data (retention policy).
+
+:Media Set: A group of continuously written tapes (all from the same
+   media pool).
+
+:Tape drive: The decive used to read and write data to the tape. There
+   are standalone drives, but drives often ship within tape libraries.
+
+:Tape changer: A device which can change the tapes inside a tape drive
+   (tape robot). They are usually part of a tape library.
+
+.. _Tape Library: https://en.wikipedia.org/wiki/Tape_library
+
+:`Tape library`_: A storage device that contains one or more tape drives,
+   a number of slots to hold tape cartridges, a barcode reader to
+   identify tape cartridges and an automated method for loading tapes
+   (a robot).
+
+   People als call this 'autoloader', 'tape robot' or 'tape jukebox'.
+
+:Inventory: The inventory stores the list of known tapes (with
+   additional status information).
+
+:Catalog: A media catalog stores information about the media content.
+
+
+Tape Quickstart
+---------------
+
+1. Configure your tape hardware (drives and changers)
+
+2. Configure one or more media pools
+
+3. Label your tape cartridges.
+
+4. Start your first tape backup job ...
+
+
+Configuration
+-------------
+
+Please note that you can configure anything using the graphical user
+interface or the command line interface. Both methods results in the
+same configuration.
+
+
+Tape changers
+~~~~~~~~~~~~~
+
+Tape changers (robots) are part of a `Tape Library`_. You can skip
+this step if you are using a standalone drive.
+
+Linux is able to auto detect those devices, and you can get a list
+of available devices using::
+
+ # proxmox-tape changer scan
+ ┌─────────────────────────────┬─────────┬──────────────┬────────┐
+ │ path                        │ vendor  │ model        │ serial │
+ ╞═════════════════════════════╪═════════╪══════════════╪════════╡
+ │ /dev/tape/by-id/scsi-CC2C52 │ Quantum │ Superloader3 │ CC2C52 │
+ └─────────────────────────────┴─────────┴──────────────┴────────┘
+
+In order to use that device with Proxmox, you need to create a
+configuration entry::
+
+ # proxmox-tape changer create sl3 --path /dev/tape/by-id/scsi-CC2C52
+
+Where ``sl3`` is an arbitrary name you can choose.
+
+.. Note:: Please use stable device path names from inside
+   ``/dev/tape/by-id/``. Names like ``/dev/sg0`` may point to a
+   different device after reboot, and that is not what you want.
+
+You can show the final configuration with::
+
+ # proxmox-tape changer config sl3
+ ┌──────┬─────────────────────────────┐
+ │ Name │ Value                       │
+ ╞══════╪═════════════════════════════╡
+ │ name │ sl3                         │
+ ├──────┼─────────────────────────────┤
+ │ path │ /dev/tape/by-id/scsi-CC2C52 │
+ └──────┴─────────────────────────────┘
+
+Or simply list all configured changer devices::
+
+ # proxmox-tape changer list
+ ┌──────┬─────────────────────────────┬─────────┬──────────────┬────────────┐
+ │ name │ path                        │ vendor  │ model        │ serial     │
+ ╞══════╪═════════════════════════════╪═════════╪══════════════╪════════════╡
+ │ sl3  │ /dev/tape/by-id/scsi-CC2C52 │ Quantum │ Superloader3 │ CC2C52     │
+ └──────┴─────────────────────────────┴─────────┴──────────────┴────────────┘
+
+The Vendor, Model and Serial number are auto detected, but only shown
+if the device is online.
+
+To test your setup, please query the status of the changer device with::
+
+ # proxmox-tape changer status sl3
+ ┌───────────────┬──────────┬────────────┬─────────────┐
+ │ entry-kind    │ entry-id │ changer-id │ loaded-slot │
+ ╞═══════════════╪══════════╪════════════╪═════════════╡
+ │ drive         │        0 │ vtape1     │           1 │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ slot          │        1 │            │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ slot          │        2 │ vtape2     │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ ...           │      ... │            │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ slot          │       16 │            │             │
+ └───────────────┴──────────┴────────────┴─────────────┘
+
+Tape libraries usually provide some special import/export slots (also
+called "mail slots"). Tapes inside those slots are acessible from
+outside, making it easy to add/remove tapes to/from the library. Those
+tapes are considered to be "offline", so backup jobs will not use
+them. Those special slots are auto-detected and marked as
+``import-export`` slot in the status command.
+
+It's worth noting that some of the smaller tape libraries don't have
+such slots. While they have something called "Mail Slot", that slot
+is just a way to grab the tape from the gripper. But they are unable
+to hold media while the robot does other things. They also do not
+expose that "Mail Slot" over the SCSI interface, so you wont see them in
+the status output.
+
+As a workaround, you can mark some of the normal slots as export
+slot. The software treats those slots like real ``import-export``
+slots, and the media inside those slots is considered to be 'offline'
+(not available for backup)::
+
+ # proxmox-tape changer update sl3 --export-slots 15,16
+
+After that, you can see those artificial ``import-export`` slots in
+the status output::
+
+ # proxmox-tape changer status sl3
+ ┌───────────────┬──────────┬────────────┬─────────────┐
+ │ entry-kind    │ entry-id │ changer-id │ loaded-slot │
+ ╞═══════════════╪══════════╪════════════╪═════════════╡
+ │ drive         │        0 │ vtape1     │           1 │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ import-export │       15 │            │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ import-export │       16 │            │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ slot          │        1 │            │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ slot          │        2 │ vtape2     │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ ...           │      ... │            │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ slot          │       14 │            │             │
+ └───────────────┴──────────┴────────────┴─────────────┘
+
+
+Tape drives
+~~~~~~~~~~~
+
+Linux is able to auto detect tape drives, and you can get a list
+of available tape drives using::
+
+ # proxmox-tape drive scan
+ ┌────────────────────────────────┬────────┬─────────────┬────────┐
+ │ path                           │ vendor │ model       │ serial │
+ ╞════════════════════════════════╪════════╪═════════════╪════════╡
+ │ /dev/tape/by-id/scsi-12345-nst │ IBM    │ ULT3580-TD4 │  12345 │
+ └────────────────────────────────┴────────┴─────────────┴────────┘
+
+In order to use that drive with Proxmox, you need to create a
+configuration entry::
+
+ # proxmox-tape drive create mydrive --path  /dev/tape/by-id/scsi-12345-nst
+
+.. Note:: Please use stable device path names from inside
+   ``/dev/tape/by-id/``. Names like ``/dev/nst0`` may point to a
+   different device after reboot, and that is not what you want.
+
+If you have a tape library, you also need to set the associated
+changer device::
+
+ # proxmox-tape drive update mydrive --changer sl3  --changer-drivenum 0
+
+The ``--changer-drivenum`` is only necessary if the tape library
+includes more than one drive (The changer status command lists all
+drivenums).
+
+You can show the final configuration with::
+
+ # proxmox-tape drive config mydrive
+ ┌─────────┬────────────────────────────────┐
+ │ Name    │ Value                          │
+ ╞═════════╪════════════════════════════════╡
+ │ name    │ mydrive                        │
+ ├─────────┼────────────────────────────────┤
+ │ path    │ /dev/tape/by-id/scsi-12345-nst │
+ ├─────────┼────────────────────────────────┤
+ │ changer │ sl3                            │
+ └─────────┴────────────────────────────────┘
+
+.. NOTE:: The ``changer-drivenum`` value 0 is not stored in the
+   configuration, because that is the default.
+
+To list all configured drives use::
+
+ # proxmox-tape drive list
+ ┌──────────┬────────────────────────────────┬─────────┬────────┬─────────────┬────────┐
+ │ name     │ path                           │ changer │ vendor │ model       │ serial │
+ ╞══════════╪════════════════════════════════╪═════════╪════════╪═════════════╪════════╡
+ │ mydrive  │ /dev/tape/by-id/scsi-12345-nst │ sl3     │ IBM    │ ULT3580-TD4 │ 12345  │
+ └──────────┴────────────────────────────────┴─────────┴────────┴─────────────┴────────┘
+
+The Vendor, Model and Serial number are auto detected, but only shown
+if the device is online.
+
+For testing, you can simply query the drive status with::
+
+ # proxmox-tape status --drive mydrive
+ ┌───────────┬────────────────────────┐
+ │ Name      │ Value                  │
+ ╞═══════════╪════════════════════════╡
+ │ blocksize │ 0                      │
+ ├───────────┼────────────────────────┤
+ │ status    │ DRIVE_OPEN | IM_REP_EN │
+ └───────────┴────────────────────────┘
+
+.. NOTE:: Blocksize should always be 0 (variable block size
+   mode). This is the default anyways.
+
+
+Media Pools
+~~~~~~~~~~~
+
+A media pool is a logical container for tapes. A backup job targets
+one media pool, so a job only uses tapes from that pool.
+
+.. topic:: Media Set
+
+   A media set is a group of continuously written tapes, used to split
+   the larger pool into smaller, restorable units. One or more backup
+   jobs write to a media set, producing an ordered group of
+   tapes. Media sets are identified by an unique ID. That ID and the
+   sequence number is stored on each tape of that set (tape label).
+
+   Media sets are the basic unit for restore tasks, i.e. you need all
+   tapes in the set to restore the media set content. Data is fully
+   deduplicated inside a media set.
+
+
+.. topic:: Media Set Allocation Policy
+
+   The pool additionally defines how long backup jobs can append data
+   to a media set. The following settings are possible:
+
+   - Try to use the current media set.
+
+     This setting produce one large media set. While this is very
+     space efficient (deduplication, no unused space), it can lead to
+     long restore times, because restore jobs needs to read all tapes in the
+     set.
+
+     .. NOTE:: Data is fully deduplicated inside a media set. That
+        also means that data is randomly distributed over the tapes in
+        the set. So even if you restore a single VM, this may have to
+        read data from all tapes inside the media set.
+
+     Larger media sets are also more error prone, because a single
+     damaged media makes the restore fail.
+
+     Usage scenario: Mostly used with tape libraries, and you manually
+     trigger new set creation by running a backup job with the
+     ``--export`` option.
+
+     .. NOTE:: Retention period starts with the existence of a newer
+	media set.
+
+   - Always create a new media set.
+
+     With this setting each backup job creates a new media set. This
+     is less space efficient, because the last media from the last set
+     may not be fully written, leaving the remaining space unused.
+
+     The advantage is that this procudes media sets of minimal
+     size. Small set are easier to handle, you can move sets to an
+     off-site vault, and restore is much faster.
+
+     .. NOTE:: Retention period starts with the creation time of the
+        media set.
+
+   - Create a new set when the specified Calendar Event triggers.
+
+     .. _systemd.time manpage: https://manpages.debian.org/buster/systemd/systemd.time.7.en.html
+
+     This allows you to specify points in time by using systemd like
+     Calendar Event specifications (see `systemd.time manpage`_).
+
+     For example, the value ``weekly`` (or ``Mon *-*-* 00:00:00``)
+     will create a new set each week.
+
+     This balances between space efficency and media count.
+
+     .. NOTE:: Retention period starts when the calendar event
+        triggers.
+
+   Additionally, the following events may allocate a new media set:
+
+   - Required tape is offline (and you use a tape library).
+
+   - Current set contains damaged of retired tapes.
+
+   - Media pool encryption changed
+
+   - Database consistency errors, e.g. if the inventory does not
+     contain required media info, or contain conflicting infos
+     (outdated data).
+
+.. topic:: Retention Policy
+
+   Defines how long we want to keep the data.
+
+   - Always overwrite media.
+
+   - Protect data for the duration specified.
+
+     We use systemd like time spans to specify durations, e.g. ``2
+     weeks`` (see `systemd.time manpage`_).
+
+   - Never overwrite data.
+
+.. topic:: Hardware Encryption
+
+   LTO4 (or later) tape drives support hardware encryption. If you
+   configure the media pool to use encryption, all data written to the
+   tapes is encrypted using the configured key.
+
+   That way, unauthorized users cannot read data from the media,
+   e.g. if you loose a media while shipping to an offsite location.
+
+   .. Note:: If the backup client also encrypts data, data on tape
+      will be double encrypted.
+
+   The password protected key is stored on each media, so it is
+   possbible to `restore the key <restore_encryption_key_>`_ using the password. Please make sure
+   you remember the password in case you need to restore the key.
+
+
+.. NOTE:: FIXME: Add note about global content namespace. (We do not store
+   the source datastore, so it is impossible to distinguish
+   store1:/vm/100 from store2:/vm/100. Please use different media
+   pools if the source is from a different name space)
+
+
+The following command creates a new media pool::
+
+ // proxmox-tape pool create <name> --drive <string> [OPTIONS]
+
+ # proxmox-tape pool create daily --drive mydrive
+
+
+Additional option can be set later using the update command::
+
+ # proxmox-tape pool update daily --allocation daily --retention 7days
+
+
+To list all configured pools use::
+
+ # proxmox-tape pool list
+ ┌───────┬──────────┬────────────┬───────────┬──────────┐
+ │ name  │ drive    │ allocation │ retention │ template │
+ ╞═══════╪══════════╪════════════╪═══════════╪══════════╡
+ │ daily │ mydrive  │ daily      │ 7days     │          │
+ └───────┴──────────┴────────────┴───────────┴──────────┘
+
+
+Tape Jobs
+~~~~~~~~~
+
+
+Administration
+--------------
+
+Many sub-command of the ``proxmox-tape`` command line tools take a
+parameter called ``--drive``, which specifies the tape drive you want
+to work on. For convenience, you can set that in an environment
+variable::
+
+ # export PROXMOX_TAPE_DRIVE=mydrive
+
+You can then omit the ``--drive`` parameter from the command. If the
+drive has an associated changer device, you may also omit the changer
+parameter from commands that needs a changer device, for example::
+
+ # proxmox-tape changer status
+
+Should displays the changer status of the changer device associated with
+drive ``mydrive``.
+
+
+Label Tapes
+~~~~~~~~~~~
+
+By default, tape cartidges all looks the same, so you need to put a
+label on them for unique identification. So first, put a sticky paper
+label with some human readable text on the cartridge.
+
+If you use a `Tape Library`_, you should use an 8 character string
+encoded as `Code 39`_, as definded in the `LTO Ultrium Cartridge Label
+Specification`_. You can either bye such barcode labels from your
+cartidge vendor, or print them yourself. You can use our `LTO Barcode
+Generator`_ App for that.
+
+Next, you need to write that same label text to the tape, so that the
+software can uniquely identify the tape too.
+
+For a standalone drive, manually insert the new tape cartidge into the
+drive and run::
+
+ # proxmox-tape label --changer-id <label-text> [--pool <pool-name>]
+
+You may omit the ``--pool`` argument to allow the tape to be used by any pool.
+
+.. Note:: For safety reasons, this command fails if the tape contain
+   any data. If you want to overwrite it anways, erase the tape first.
+
+You can verify success by reading back the label::
+
+ # proxmox-tape read-label
+ ┌─────────────────┬──────────────────────────────────────┐
+ │ Name            │ Value                                │
+ ╞═════════════════╪══════════════════════════════════════╡
+ │ changer-id      │ vtape1                               │
+ ├─────────────────┼──────────────────────────────────────┤
+ │ uuid            │ 7f42c4dd-9626-4d89-9f2b-c7bc6da7d533 │
+ ├─────────────────┼──────────────────────────────────────┤
+ │ ctime           │ Wed Jan  6 09:07:51 2021             │
+ ├─────────────────┼──────────────────────────────────────┤
+ │ pool            │ daily                                │
+ ├─────────────────┼──────────────────────────────────────┤
+ │ media-set-uuid  │ 00000000-0000-0000-0000-000000000000 │
+ ├─────────────────┼──────────────────────────────────────┤
+ │ media-set-ctime │ Wed Jan  6 09:07:51 2021             │
+ └─────────────────┴──────────────────────────────────────┘
+
+.. NOTE:: The ``media-set-uuid`` using all zeros indicates an empty
+   tape (not used by any media set).
+
+If you have a tape library, apply the sticky barcode label to the tape
+cartridges first. Then load those empty tapes into the library. You
+can then label all unlabeled tapes with a single command::
+
+ # proxmox-tape barcode-label [--pool <pool-name>]
+
+
+Run Tape Backups
+~~~~~~~~~~~~~~~~
+
+To manually run a backup job use::
+
+ # proxmox-tape backup <store> <pool> [OPTIONS]
+
+The following options are available:
+
+--eject-media  Eject media upon job completion.
+
+  It is normally good practice to eject the tape after use. This unmounts the
+  tape from the drive and prevents the tape from getting dirty with dust.
+
+--export-media-set  Export media set upon job completion.
+
+  After a sucessful backup job, this moves all tapes from the used
+  media set into import-export slots. The operator can then pick up
+  those tapes and move them to a media vault.
+
+
+Restore from Tape
+~~~~~~~~~~~~~~~~~
+
+Restore is done at media-set granularity, so you first need to find
+out which media set contains the data you want to restore. This
+information is stored in the media catalog. If you do not have media
+catalogs, you need to restore them first. Please note that you need
+the catalog to find your data, but restoring a complete media-set does
+not need media catalogs.
+
+The following command shows the media content (from catalog)::
+
+ # proxmox-tape media content
+ ┌────────────┬──────┬──────────────────────────┬────────┬────────────────────────────────┬──────────────────────────────────────┐
+ │ label-text │ pool │ media-set-name           │ seq-nr │ snapshot                       │ media-set-uuid                       │
+ ╞════════════╪══════╪══════════════════════════╪════════╪════════════════════════════════╪══════════════════════════════════════╡
+ │ TEST01L8   │ p2   │ Wed Jan 13 13:55:55 2021 │      0 │ vm/201/2021-01-11T10:43:48Z    │ 9da37a55-aac7-4deb-91c6-482b3b675f30 │
+ ├────────────┼──────┼──────────────────────────┼────────┼────────────────────────────────┼──────────────────────────────────────┤
+ │        ... │ ...  │                      ... │    ... │ ...                            │                                  ... │
+ └────────────┴──────┴──────────────────────────┴────────┴────────────────────────────────┴──────────────────────────────────────┘
+
+
+A restore job reads the data from the media set and moves it back to
+data disk (datastore)::
+
+ // proxmox-tape restore <media-set-uuid> <datastore>
+
+ # proxmox-tape restore 9da37a55-aac7-4deb-91c6-482b3b675f30 mystore
+
+
+Update Inventory
+~~~~~~~~~~~~~~~~
+
+
+Restore Catalog
+~~~~~~~~~~~~~~~
+
+
+Encryption Key Management
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creating a new encryption key::
+
+ # proxmox-tape key create --hint "tape pw 2020"
+ Tape Encryption Key Password: **********
+ Verify Password: **********
+ "14:f8:79:b9:f5:13:e5:dc:bf:b6:f9:88:48:51:81:dc:79:bf:a0:22:68:47:d1:73:35:2d:b6:20:e1:7f:f5:0f"
+
+List existing encryption keys::
+
+ # proxmox-tape key list
+ ┌───────────────────────────────────────────────────┬───────────────┐
+ │ fingerprint                                       │ hint          │
+ ╞═══════════════════════════════════════════════════╪═══════════════╡
+ │ 14:f8:79:b9:f5:13:e5:dc: ...   :b6:20:e1:7f:f5:0f │ tape pw 2020  │
+ └───────────────────────────────────────────────────┴───────────────┘
+
+To show encryption key details::
+
+ # proxmox-tape key show 14:f8:79:b9:f5:13:e5:dc:...:b6:20:e1:7f:f5:0f
+ ┌─────────────┬───────────────────────────────────────────────┐
+ │ Name        │ Value                                         │
+ ╞═════════════╪═══════════════════════════════════════════════╡
+ │ kdf         │ scrypt                                        │
+ ├─────────────┼───────────────────────────────────────────────┤
+ │ created     │ Sat Jan 23 14:47:21 2021                      │
+ ├─────────────┼───────────────────────────────────────────────┤
+ │ modified    │ Sat Jan 23 14:47:21 2021                      │
+ ├─────────────┼───────────────────────────────────────────────┤
+ │ fingerprint │ 14:f8:79:b9:f5:13:e5:dc:...:b6:20:e1:7f:f5:0f │
+ ├─────────────┼───────────────────────────────────────────────┤
+ │ hint        │ tape pw 2020                                  │
+ └─────────────┴───────────────────────────────────────────────┘
+
+The ``paperkey`` subcommand can be used to create a QR encoded
+version of a tape encryption key. The following command sends the output of the
+``paperkey`` command to a text file, for easy printing::
+
+ proxmox-tape key paperkey <fingerprint> --output-format text > qrkey.txt
+
+
+.. _restore_encryption_key:
+
+Restoring Encryption Keys
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can restore the encryption key from the tape, using the password
+used to generate the key. First, load the tape you want to restore
+into the drive. Then run::
+
+ # proxmox-tape key restore
+ Tepe Encryption Key Password: ***********
+
+If the password is correct, the key will get imported to the
+database. Further restore jobs automatically use any availbale key.
+
+
+Tape Cleaning
+~~~~~~~~~~~~~
+
+LTO tape drives requires regular cleaning. This is done by loading a
+cleaning cartridge into the drive, which is a manual task for
+standalone drives.
+
+For tape libraries, cleaning cartridges are identified using special
+labels starting with letters "CLN". For example, our tape library has a
+cleaning cartridge inside slot 3::
+
+ # proxmox-tape changer status sl3
+ ┌───────────────┬──────────┬────────────┬─────────────┐
+ │ entry-kind    │ entry-id │ changer-id │ loaded-slot │
+ ╞═══════════════╪══════════╪════════════╪═════════════╡
+ │ drive         │        0 │ vtape1     │           1 │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ slot          │        1 │            │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ slot          │        2 │ vtape2     │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ slot          │        3 │ CLN001CU   │             │
+ ├───────────────┼──────────┼────────────┼─────────────┤
+ │ ...           │      ... │            │             │
+ └───────────────┴──────────┴────────────┴─────────────┘
+
+To initiate a cleaning operation simply run::
+
+ # proxmox-tape clean
+
+This command does the following:
+
+- find the cleaning tape (in slot 3)
+
+- unload the current media from the drive (back to slot1)
+
+- load the cleaning tape into the drive
+
+- run drive cleaning operation
+
+- unload the cleaning tape (to slot 3)

docs/technical-overview.rst

@@ -0,0 +1,166 @@
+Technical Overview
+==================
+
+.. _technical_overview:
+
+Datastores
+----------
+
+A Datastore is the logical place where :ref:`Backup Snapshots
+<backup_snapshot>` and their chunks are stored. Snapshots consist of a
+manifest, blobs, dynamic- and fixed-indexes (see :ref:`terminology`), and are
+stored in the following directory structure:
+
+ <datastore-root>/<type>/<id>/<time>/
+
+The deduplication of datastores is based on reusing chunks, which are
+referenced by the indexes in a backup snapshot. This means that multiple
+indexes can reference the same chunks, reducing the amount of space needed to
+contain the data (even across backup snapshots).
+
+Chunks
+------
+
+A chunk is some (possibly encrypted) data with a CRC-32 checksum at the end and
+a type marker at the beginning. It is identified by the SHA-256 checksum of its
+content.
+
+To generate such chunks, backup data is split either into fixed-size or
+dynamically sized chunks. The same content will be hashed to the same checksum.
+
+The chunks of a datastore are found in
+
+ <datastore-root>/.chunks/
+
+This chunk directory is further subdivided by the first four byte of the chunks
+checksum, so the chunk with the checksum
+
+ a342e8151cbf439ce65f3df696b54c67a114982cc0aa751f2852c2f7acc19a8b
+
+lives in
+
+ <datastore-root>/.chunks/a342/
+
+This is done to reduce the number of files per directory, as having many files
+per directory can be bad for file system performance.
+
+These chunk directories ('0000'-'ffff') will be preallocated when a datastore
+is created.
+
+Fixed-sized Chunks
+^^^^^^^^^^^^^^^^^^
+
+For block based backups (like VMs), fixed-sized chunks are used. The content
+(disk image), is split into chunks of the same length (typically 4 MiB).
+
+This works very well for VM images, since the file system on the guest most
+often tries to allocate files in contiguous pieces, so new files get new
+blocks, and changing existing files changes only their own blocks.
+
+As an optimization, VMs in `Proxmox VE`_ can make use of 'dirty bitmaps', which
+can track the changed blocks of an image. Since these bitmap are also a
+representation of the image split into chunks, there is a direct relation
+between dirty blocks of the image and chunks which need to get uploaded, so
+only modified chunks of the disk have to be uploaded for a backup.
+
+Since the image is always split into chunks of the same size, unchanged blocks
+will result in identical checksums for those chunks, so such chunks do not need
+to be backed up again. This way storage snapshots are not needed to find the
+changed blocks.
+
+For consistency, `Proxmox VE`_ uses a QEMU internal snapshot mechanism, that
+does not rely on storage snapshots either.
+
+Dynamically sized Chunks
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If one does not want to backup block-based systems but rather file-based
+systems, using fixed-sized chunks is not a good idea, since every time a file
+would change in size, the remaining data gets shifted around and this would
+result in many chunks changing, reducing the amount of deduplication.
+
+To improve this, `Proxmox Backup`_ Server uses dynamically sized chunks
+instead. Instead of splitting an image into fixed sizes, it first generates a
+consistent file archive (:ref:`pxar <pxar-format>`) and uses a rolling hash
+over this on-the-fly generated archive to calculate chunk boundaries.
+
+We use a variant of Buzhash which is a cyclic polynomial algorithm.  It works
+by continuously calculating a checksum while iterating over the data, and on
+certain conditions it triggers a hash boundary.
+
+Assuming that most files of the system that is to be backed up have not
+changed, eventually the algorithm triggers the boundary on the same data as a
+previous backup, resulting in chunks that can be reused.
+
+Encrypted Chunks
+^^^^^^^^^^^^^^^^
+
+Encrypted chunks are a special case. Both fixed- and dynamically sized chunks
+can be encrypted, and they are handled in a slightly different manner than
+normal chunks.
+
+The hashes of encrypted chunks are calculated not with the actual (encrypted)
+chunk content, but with the plaintext content concatenated with the encryption
+key. This way, two chunks of the same data encrypted with different keys
+generate two different checksums and no collisions occur for multiple
+encryption keys.
+
+This is done to speed up the client part of the backup, since it only needs to
+encrypt chunks that are actually getting uploaded. Chunks that exist already in
+the previous backup, do not need to be encrypted and uploaded.
+
+Caveats and Limitations
+-----------------------
+
+Notes on hash collisions
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Every hashing algorithm has a chance to produce collisions, meaning two (or
+more) inputs generate the same checksum. For SHA-256, this chance is
+negligible.  To calculate such a collision, one can use the ideas of the
+'birthday problem' from probability theory. For big numbers, this is actually
+infeasible to calculate with regular computers, but there is a good
+approximation:
+
+.. math::
+
+ p(n, d) = 1 - e^{-n^2/(2d)}
+
+Where `n` is the number of tries, and `d` is the number of possibilities.
+For a concrete example lets assume a large datastore of 1 PiB, and an average
+chunk size of 4 MiB. That means :math:`n = 268435456` tries, and :math:`d =
+2^{256}` possibilities. Inserting those values in the formula from earlier you
+will see that the probability of a collision in that scenario is:
+
+.. math::
+
+ 3.1115 * 10^{-61}
+
+For context, in a lottery game of guessing 6 out of 45, the chance to correctly
+guess all 6 numbers is only :math:`1.2277 * 10^{-7}`, that means the chance of
+collission is about the same as winning 13 such lotto games *in a row*.
+
+In conclusion, it is extremely unlikely that such a collision would occur by
+accident in a normal datastore.
+
+Additionally, SHA-256 is prone to length extension attacks, but since there is
+an upper limit for how big the chunk are, this is not a problem, since a
+potential attacker cannot arbitrarily add content to the data beyond that
+limit.
+
+File-based Backup
+^^^^^^^^^^^^^^^^^
+
+Since dynamically sized chunks (for file-based backups) are created on a custom
+archive format (pxar) and not over the files directly, there is no relation
+between files and the chunks. This means  that the Proxmox Backup client has to
+read all files again for every backup, otherwise it would not be possible to
+generate a consistent independent pxar archive where the original chunks can be
+reused. Note that there will be still only new or change chunks be uploaded.
+
+Verification of encrypted chunks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For encrypted chunks, only the checksum of the original (plaintext) data is
+available, making it impossible for the server (without the encryption key), to
+verify its content against it. Instead only the CRC-32 checksum gets checked.

docs/terminology.rst

@@ -0,0 +1,121 @@
+.. _terminology:
+
+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:
+
+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/user-management.rst

@@ -0,0 +1,387 @@
+.. _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 add a new
+user with the ``user create`` subcommand or through the web
+interface, under the **User Management** tab of **Configuration -> Access
+Control**. 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 Access Control
+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_tokens:
+
+API Tokens
+----------
+
+.. image:: images/screenshots/pbs-gui-apitoken-overview.png
+  :align: right
+  :alt: API Token Overview
+
+Any authenticated user can generate API tokens which can in turn be used to
+configure various clients, instead of directly providing the username and
+password.
+
+API tokens serve two purposes:
+
+#. Easy revocation in case client gets compromised
+#. Limit permissions for each client/token within the users' permission
+
+An API token consists of two parts: an identifier consisting of the user name,
+the realm and a tokenname (``user@realm!tokenname``), and a secret value. Both
+need to be provided to the client in place of the user ID (``user@realm``) and
+the user password, respectively.
+
+.. image:: images/screenshots/pbs-gui-apitoken-secret-value.png
+  :align: right
+  :alt: API secret value
+
+The API token is passed from the client to the server by setting the
+``Authorization`` HTTP header with method ``PBSAPIToken`` to the value
+``TOKENID:TOKENSECRET``.
+
+Generating new tokens can done using ``proxmox-backup-manager`` or the GUI:
+
+.. code-block:: console
+
+  # proxmox-backup-manager user generate-token john@pbs client1
+  Result: {
+    "tokenid": "john@pbs!client1",
+    "value": "d63e505a-e3ec-449a-9bc7-1da610d4ccde"
+  }
+
+.. note:: The displayed secret value needs to be saved, since it cannot be
+  displayed again after generating the API token.
+
+The ``user list-tokens`` sub-command can be used to display tokens and their
+metadata:
+
+.. code-block:: console
+
+  # proxmox-backup-manager user list-tokens john@pbs
+  ┌──────────────────┬────────┬────────┬─────────┐
+  │ tokenid          │ enable │ expire │ comment │
+  ╞══════════════════╪════════╪════════╪═════════╡
+  │ john@pbs!client1 │      1 │        │         │
+  └──────────────────┴────────┴────────┴─────────┘
+
+Similarly, the ``user delete-token`` subcommand can be used to delete a token
+again.
+
+Newly generated API tokens don't have any permissions. Please read the next
+section to learn how to set access permissions.
+
+
+.. _user_acl:
+
+Access Control
+--------------
+
+By default new users and API tokens 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/tokens 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-user-management-add-user.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(s)/token(s) for which the permission is set
+#. The role being set
+
+You can manage permissions via **Configuration -> Access Control ->
+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 --auth-id john@pbs
+
+You can list the ACLs of each user/token using the following command:
+
+.. code-block:: console
+
+   # proxmox-backup-manager acl list
+   ┌──────────┬───────────────────┬───────────┬────────────────┐
+   │ ugid     │ path              │ propagate │ roleid         │
+   ╞══════════╪═══════════════════╪═══════════╪════════════════╡
+   │ john@pbs │ /datastore/store1 │         1 │ DatastoreAdmin │
+   └──────────┴───────────────────┴───────────┴────────────────┘
+
+A single user/token 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.
+
+API Token permissions
+~~~~~~~~~~~~~~~~~~~~~
+
+API token permissions are calculated based on ACLs containing their ID
+independent of those of their corresponding user. The resulting permission set
+on a given path is then intersected with that of the corresponding user.
+
+In practice this means:
+
+#. API tokens require their own ACL entries
+#. API tokens can never do more than their corresponding user
+
+Effective permissions
+~~~~~~~~~~~~~~~~~~~~~
+
+To calculate and display the effective permission set of a user or API token
+you can use the ``proxmox-backup-manager user permission`` command:
+
+.. code-block:: console
+
+  # proxmox-backup-manager user permissions john@pbs --path /datastore/store1
+  Privileges with (*) have the propagate flag set
+  
+  Path: /datastore/store1
+  - Datastore.Audit (*)
+  - Datastore.Backup (*)
+  - Datastore.Modify (*)
+  - Datastore.Prune (*)
+  - Datastore.Read (*)
+  - Datastore.Verify (*)
+  
+  # proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1'
+  # proxmox-backup-manager user permissions 'john@pbs!client1' --path /datastore/store1
+  Privileges with (*) have the propagate flag set
+  
+  Path: /datastore/store1
+  - Datastore.Backup (*)
+
+.. _user_tfa:
+Two-factor authentication
+-------------------------
+
+Introduction
+~~~~~~~~~~~~
+
+Simple authentication requires only secret piece of evidence (one factor) that
+a user can successfully claim a identiy (authenticate), for example, that you
+are allowed to login as `root@pam` on a specific Proxmox Backup Server.
+If the password gets stolen, or leaked in another way, anybody can use it to
+login - even if they should not be allowed to do so.
+
+With Two-factor authentication (TFA) a user is asked for an additional factor,
+to proof his authenticity. The extra factor is different from a password
+(something only the user knows), it is something only the user has, for example
+a piece of hardware (security key) or an secret saved on the users smartphone.
+
+This means that a remote user can never get hold on such a physical object. So,
+even if that user would know your password they cannot successfully
+authenticate as you, as your second factor is missing.
+
+.. image:: images/screenshots/pbs-gui-tfa-login.png
+  :align: right
+  :alt: Add a new user
+
+Available Second Factors
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can setup more than one second factor to avoid that losing your smartphone
+or security key permanently locks you out from your account.
+
+There are three different two-factor authentication methods supported:
+
+* TOTP (`Time-based One-Time Password <https://en.wikipedia.org/wiki/Time-based_One-Time_Password>`_).
+  A short code derived from a shared secret and the current time, it switches
+  every 30 seconds.
+
+* WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_).
+  A general standard for authentication. It is implemented by various security
+  devices like hardware keys or trusted platform modules (TPM) from a computer
+  or smart phone.
+
+* Single use Recovery Keys. A list of keys which should either be printed out
+  and locked in a secure fault or saved digitally in a electronic vault.
+  Each key can be used only once, they are perfect for ensuring you are not
+  locked out even if all of your other second factors are lost or corrupt.
+
+
+Setup
+~~~~~
+
+.. _user_tfa_setup_totp:
+TOTP
+^^^^
+
+.. image:: images/screenshots/pbs-gui-tfa-add-totp.png
+  :align: right
+  :alt: Add a new user
+
+There is not server setup required, simply install a TOTP app on your
+smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the
+Proxmox Backup Server web-interface to add a TOTP factor.
+
+.. _user_tfa_setup_webauthn:
+WebAuthn
+^^^^^^^^
+
+For WebAuthn to work you need to have two things:
+
+* a trusted HTTPS certificate (for example, by using `Let's Encrypt
+  <https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_)
+
+* setup the WebAuthn configuration (see *Configuration -> Authentication* in the
+  Proxmox Backup Server web-interface). This can be auto-filled in most setups.
+
+Once you fullfilled both of those requirements, you can add a WebAuthn
+configuration in the *Access Control* panel.
+
+.. _user_tfa_setup_recovery_keys:
+Recovery Keys
+^^^^^^^^^^^^^
+
+.. image:: images/screenshots/pbs-gui-tfa-add-recovery-keys.png
+  :align: right
+  :alt: Add a new user
+
+Recovery key codes do not need any preparation, you can simply create a set of
+recovery keys in the *Access Control* panel.
+
+.. note:: There can only be one set of single-use recovery keys per user at any
+ time.
+
+TFA and Automated Access
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Two-factor authentication is only implemented for the web-interface, you should
+use :ref:`API Tokens <user_tokens>` for all other use cases, especially
+non-interactive ones (for example, adding a Proxmox Backup server to Proxmox VE
+as a storage).

etc/Makefile

@@ -1,13 +1,15 @@
 include ../defines.mk
 
-UNITS :=
+UNITS := \
+	proxmox-backup-daily-update.timer \
 
 DYNAMIC_UNITS := \
 	proxmox-backup-banner.service \
+	proxmox-backup-daily-update.service \
 	proxmox-backup.service \
 	proxmox-backup-proxy.service
 
-all: $(UNITS) $(DYNAMIC_UNITS) pbstest-beta.list
+all: $(UNITS) $(DYNAMIC_UNITS) pbs-enterprise.list
 
 clean:
 	rm -f $(DYNAMIC_UNITS)

etc/pbs-enterprise.list

@@ -0,0 +1 @@
+deb https://enterprise.proxmox.com/debian/pbs buster pbs-enterprise

etc/pbstest-beta.list

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

etc/proxmox-backup-daily-update.service.in

@@ -0,0 +1,8 @@
+[Unit]
+Description=Daily Proxmox Backup Server update and maintenance activities
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=%LIBEXECDIR%/proxmox-backup/proxmox-daily-update

etc/proxmox-backup-daily-update.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Daily Proxmox Backup Server update and maintenance activities
+
+[Timer]
+OnCalendar=*-*-* 1:00
+RandomizedDelaySec=5h
+Persistent=true
+
+[Install]
+WantedBy=timers.target

etc/proxmox-backup-proxy.service.in

@@ -9,6 +9,7 @@ After=proxmox-backup.service
 Type=notify
 ExecStart=%LIBEXECDIR%/proxmox-backup/proxmox-backup-proxy
 ExecReload=/bin/kill -HUP $MAINPID
+PIDFile=/run/proxmox-backup/proxy.pid
 Restart=on-failure
 User=%PROXY_USER%
 Group=%PROXY_USER%

etc/proxmox-backup.service.in

@@ -7,6 +7,7 @@ After=network.target
 Type=notify
 ExecStart=%LIBEXECDIR%/proxmox-backup/proxmox-backup-api
 ExecReload=/bin/kill -HUP $MAINPID
+PIDFile=/run/proxmox-backup/api.pid
 Restart=on-failure
 
 [Install]

examples/download-speed.rs

@@ -2,7 +2,7 @@ use std::io::Write;
 
 use anyhow::{Error};
 
-use proxmox_backup::api2::types::Userid;
+use proxmox_backup::api2::types::Authid;
 use proxmox_backup::client::{HttpClient, HttpClientOptions, BackupReader};
 
 pub struct DummyWriter {
@@ -26,13 +26,13 @@ async fn run() -> Result<(), Error> {
 
     let host = "localhost";
 
-    let username = Userid::root_userid();
+    let auth_id = Authid::root_auth_id();
 
-    let options = HttpClientOptions::new()
+    let options = HttpClientOptions::default()
         .interactive(true)
         .ticket_cache(true);
 
-    let client = HttpClient::new(host, 8007, username, options)?;
+    let client = HttpClient::new(host, 8007, auth_id, options)?;
 
     let backup_time = proxmox::tools::time::parse_rfc3339("2019-06-28T10:49:48Z")?;
 

examples/h2client.rs

@@ -2,7 +2,7 @@ use std::future::Future;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-use anyhow::{Error};
+use anyhow::Error;
 use futures::future::TryFutureExt;
 use futures::stream::Stream;
 use tokio::net::TcpStream;
@@ -38,11 +38,11 @@ impl Future for Process {
                         this.body.flow_control().release_capacity(chunk.len())?;
                         this.bytes += chunk.len();
                         // println!("GOT FRAME {}", chunk.len());
-                    },
+                    }
                     Some(Err(err)) => return Poll::Ready(Err(Error::from(err))),
                     None => {
                         this.trailers = true;
-                    },
+                    }
                 }
             }
         }
@@ -52,7 +52,6 @@ impl Future for Process {
 fn send_request(
     mut client: h2::client::SendRequest<bytes::Bytes>,
 ) -> impl Future<Output = Result<usize, Error>> {
-
     println!("sending request");
 
     let request = http::Request::builder()
@@ -62,11 +61,11 @@ fn send_request(
 
     let (response, _stream) = client.send_request(request, true).unwrap();
 
-    response
+    response.map_err(Error::from).and_then(|response| Process {
-        .map_err(Error::from)
+        body: response.into_body(),
-        .and_then(|response| {
+        trailers: false,
-            Process { body: response.into_body(), trailers: false, bytes: 0 }
+        bytes: 0,
-        })
+    })
 }
 
 fn main() -> Result<(), Error> {
@@ -74,16 +73,15 @@ fn main() -> Result<(), Error> {
 }
 
 async fn run() -> Result<(), Error> {
-
     let start = std::time::SystemTime::now();
 
-    let conn = TcpStream::connect(std::net::SocketAddr::from(([127,0,0,1], 8008)))
+    let conn = TcpStream::connect(std::net::SocketAddr::from(([127, 0, 0, 1], 8008))).await?;
-        .await?;
+    conn.set_nodelay(true).unwrap();
 
     let (client, h2) = h2::client::Builder::new()
-        .initial_connection_window_size(1024*1024*1024)
+        .initial_connection_window_size(1024 * 1024 * 1024)
-        .initial_window_size(1024*1024*1024)
+        .initial_window_size(1024 * 1024 * 1024)
-        .max_frame_size(4*1024*1024)
+        .max_frame_size(4 * 1024 * 1024)
         .handshake(conn)
         .await?;
 
@@ -99,10 +97,13 @@ async fn run() -> Result<(), Error> {
     }
 
     let elapsed = start.elapsed().unwrap();
-    let elapsed = (elapsed.as_secs() as f64) +
+    let elapsed = (elapsed.as_secs() as f64) + (elapsed.subsec_millis() as f64) / 1000.0;
-        (elapsed.subsec_millis() as f64)/1000.0;
 
-    println!("Downloaded {} bytes, {} MB/s", bytes, (bytes as f64)/(elapsed*1024.0*1024.0));
+    println!(
+        "Downloaded {} bytes, {} MB/s",
+        bytes,
+        (bytes as f64) / (elapsed * 1024.0 * 1024.0)
+    );
 
     Ok(())
 }

examples/h2s-client.rs

@@ -5,6 +5,7 @@ use std::task::{Context, Poll};
 use anyhow::{format_err, Error};
 use futures::future::TryFutureExt;
 use futures::stream::Stream;
+use tokio::net::TcpStream;
 
 // Simple H2 client to test H2 download speed using h2s-server.rs
 
@@ -37,11 +38,11 @@ impl Future for Process {
                         this.body.flow_control().release_capacity(chunk.len())?;
                         this.bytes += chunk.len();
                         // println!("GOT FRAME {}", chunk.len());
-                    },
+                    }
                     Some(Err(err)) => return Poll::Ready(Err(Error::from(err))),
                     None => {
                         this.trailers = true;
-                    },
+                    }
                 }
             }
         }
@@ -60,11 +61,11 @@ fn send_request(
 
     let (response, _stream) = client.send_request(request, true).unwrap();
 
-    response
+    response.map_err(Error::from).and_then(|response| Process {
-        .map_err(Error::from)
+        body: response.into_body(),
-        .and_then(|response| {
+        trailers: false,
-            Process { body: response.into_body(), trailers: false, bytes: 0 }
+        bytes: 0,
-        })
+    })
 }
 
 fn main() -> Result<(), Error> {
@@ -74,57 +75,51 @@ fn main() -> Result<(), Error> {
 async fn run() -> Result<(), Error> {
     let start = std::time::SystemTime::now();
 
-    let conn =
+    let conn = TcpStream::connect(std::net::SocketAddr::from(([127, 0, 0, 1], 8008))).await?;
-        tokio::net::TcpStream::connect(std::net::SocketAddr::from(([127,0,0,1], 8008))).await?;
-
     conn.set_nodelay(true).unwrap();
-    conn.set_recv_buffer_size(1024*1024).unwrap();
 
     use openssl::ssl::{SslConnector, SslMethod};
 
     let mut ssl_connector_builder = SslConnector::builder(SslMethod::tls()).unwrap();
     ssl_connector_builder.set_verify(openssl::ssl::SslVerifyMode::NONE);
-    let conn =
+    let ssl = ssl_connector_builder
-        tokio_openssl::connect(
+        .build()
-            ssl_connector_builder.build().configure()?,
+        .configure()?
-            "localhost",
+        .into_ssl("localhost")?;
-            conn,
+
-        )
+    let conn = tokio_openssl::SslStream::new(ssl, conn)?;
+    let mut conn = Box::pin(conn);
+    conn.as_mut()
+        .connect()
         .await
         .map_err(|err| format_err!("connect failed - {}", err))?;
 
     let (client, h2) = h2::client::Builder::new()
-        .initial_connection_window_size(1024*1024*1024)
+        .initial_connection_window_size(1024 * 1024 * 1024)
-        .initial_window_size(1024*1024*1024)
+        .initial_window_size(1024 * 1024 * 1024)
-        .max_frame_size(4*1024*1024)
+        .max_frame_size(4 * 1024 * 1024)
         .handshake(conn)
         .await?;
 
-    // Spawn a task to run the conn...
     tokio::spawn(async move {
-        if let Err(e) = h2.await {
+        if let Err(err) = h2.await {
-            println!("GOT ERR={:?}", e);
+            println!("GOT ERR={:?}", err);
         }
     });
 
     let mut bytes = 0;
-    for _ in 0..100 {
+    for _ in 0..2000 {
-        match send_request(client.clone()).await {
+        bytes += send_request(client.clone()).await?;
-            Ok(b) => {
-                bytes += b;
-            }
-            Err(e) => {
-                println!("ERROR {}", e);
-                return Ok(());
-            }
-        }
     }
 
     let elapsed = start.elapsed().unwrap();
-    let elapsed = (elapsed.as_secs() as f64) +
+    let elapsed = (elapsed.as_secs() as f64) + (elapsed.subsec_millis() as f64) / 1000.0;
-        (elapsed.subsec_millis() as f64)/1000.0;
 
-    println!("Downloaded {} bytes, {} MB/s", bytes, (bytes as f64)/(elapsed*1024.0*1024.0));
+    println!(
+        "Downloaded {} bytes, {} MB/s",
+        bytes,
+        (bytes as f64) / (elapsed * 1024.0 * 1024.0)
+    );
 
     Ok(())
 }

examples/h2s-server.rs

@@ -2,14 +2,12 @@ use std::sync::Arc;
 
 use anyhow::{format_err, Error};
 use futures::*;
-use hyper::{Request, Response, Body};
+use hyper::{Body, Request, Response};
-use openssl::ssl::{SslMethod, SslAcceptor, SslFiletype};
+use openssl::ssl::{SslAcceptor, SslFiletype, SslMethod};
 use tokio::net::{TcpListener, TcpStream};
 
 use proxmox_backup::configdir;
 
-// Simple H2 server to test H2 speed with h2s-client.rs
-
 fn main() -> Result<(), Error> {
     proxmox_backup::tools::runtime::main(run())
 }
@@ -19,38 +17,38 @@ async fn run() -> Result<(), Error> {
     let cert_path = configdir!("/proxy.pem");
 
     let mut acceptor = SslAcceptor::mozilla_intermediate(SslMethod::tls()).unwrap();
-    acceptor.set_private_key_file(key_path, SslFiletype::PEM)
+    acceptor
+        .set_private_key_file(key_path, SslFiletype::PEM)
         .map_err(|err| format_err!("unable to read proxy key {} - {}", key_path, err))?;
-    acceptor.set_certificate_chain_file(cert_path)
+    acceptor
+        .set_certificate_chain_file(cert_path)
         .map_err(|err| format_err!("unable to read proxy cert {} - {}", cert_path, err))?;
     acceptor.check_private_key().unwrap();
 
     let acceptor = Arc::new(acceptor.build());
 
-    let mut listener = TcpListener::bind(std::net::SocketAddr::from(([127,0,0,1], 8008))).await?;
+    let listener = TcpListener::bind(std::net::SocketAddr::from(([127, 0, 0, 1], 8008))).await?;
 
     println!("listening on {:?}", listener.local_addr());
 
     loop {
         let (socket, _addr) = listener.accept().await?;
-        tokio::spawn(handle_connection(socket, Arc::clone(&acceptor))
+        tokio::spawn(handle_connection(socket, Arc::clone(&acceptor)).map(|res| {
-            .map(|res| {
+            if let Err(err) = res {
-                if let Err(err) = res {
+                eprintln!("Error: {}", err);
-                    eprintln!("Error: {}", err);
+            }
-                }
+        }));
-            }));
     }
 }
 
-async fn handle_connection(
+async fn handle_connection(socket: TcpStream, acceptor: Arc<SslAcceptor>) -> Result<(), Error> {
-    socket: TcpStream,
-    acceptor: Arc<SslAcceptor>,
-) -> Result<(), Error> {
     socket.set_nodelay(true).unwrap();
-    socket.set_send_buffer_size(1024*1024).unwrap();
-    socket.set_recv_buffer_size(1024*1024).unwrap();
 
-    let socket = tokio_openssl::accept(acceptor.as_ref(), socket).await?;
+    let ssl = openssl::ssl::Ssl::new(acceptor.context())?;
+    let stream = tokio_openssl::SslStream::new(ssl, socket)?;
+    let mut stream = Box::pin(stream);
+
+    stream.as_mut().accept().await?;
 
     let mut http = hyper::server::conn::Http::new();
     http.http2_only(true);
@@ -61,7 +59,7 @@ async fn handle_connection(
 
     let service = hyper::service::service_fn(|_req: Request<Body>| {
         println!("Got request");
-        let buffer = vec![65u8; 1024*1024]; // nonsense [A,A,A,A...]
+        let buffer = vec![65u8; 4 * 1024 * 1024]; // nonsense [A,A,A,A...]
         let body = Body::from(buffer);
 
         let response = Response::builder()
@@ -72,7 +70,7 @@ async fn handle_connection(
         future::ok::<_, Error>(response)
     });
 
-    http.serve_connection(socket, service)
+    http.serve_connection(stream, service)
         .map_err(Error::from)
         .await?;
 

examples/h2server.rs

@@ -1,51 +1,55 @@
-use anyhow::{Error};
+use anyhow::Error;
 use futures::*;
+use hyper::{Body, Request, Response};
 
-// Simple H2 server to test H2 speed with h2client.rs
+use tokio::net::{TcpListener, TcpStream};
-
-use tokio::net::TcpListener;
-use tokio::io::{AsyncRead, AsyncWrite};
-
-use proxmox_backup::client::pipe_to_stream::PipeToSendStream;
 
 fn main() -> Result<(), Error> {
     proxmox_backup::tools::runtime::main(run())
 }
 
 async fn run() -> Result<(), Error> {
-    let mut listener = TcpListener::bind(std::net::SocketAddr::from(([127,0,0,1], 8008))).await?;
+    let listener = TcpListener::bind(std::net::SocketAddr::from(([127, 0, 0, 1], 8008))).await?;
 
     println!("listening on {:?}", listener.local_addr());
 
     loop {
         let (socket, _addr) = listener.accept().await?;
-        tokio::spawn(handle_connection(socket)
+        tokio::spawn(handle_connection(socket).map(|res| {
-            .map(|res| {
+            if let Err(err) = res {
-                if let Err(err) = res {
+                eprintln!("Error: {}", err);
-                    eprintln!("Error: {}", err);
+            }
-                }
+        }));
-            }));
     }
 }
 
-async fn handle_connection<T: AsyncRead + AsyncWrite + Unpin>(socket: T) -> Result<(), Error> {
+async fn handle_connection(socket: TcpStream) -> Result<(), Error> {
-    let mut conn = h2::server::handshake(socket).await?;
+    socket.set_nodelay(true).unwrap();
 
-    println!("H2 connection bound");
+    let mut http = hyper::server::conn::Http::new();
+    http.http2_only(true);
+    // increase window size: todo - find optiomal size
+    let max_window_size = (1 << 31) - 2;
+    http.http2_initial_stream_window_size(max_window_size);
+    http.http2_initial_connection_window_size(max_window_size);
 
-    while let Some((request, mut respond)) = conn.try_next().await? {
+    let service = hyper::service::service_fn(|_req: Request<Body>| {
-        println!("GOT request: {:?}", request);
+        println!("Got request");
+        let buffer = vec![65u8; 4 * 1024 * 1024]; // nonsense [A,A,A,A...]
+        let body = Body::from(buffer);
 
-        let response = http::Response::builder()
+        let response = Response::builder()
             .status(http::StatusCode::OK)
-            .body(())
+            .header(http::header::CONTENT_TYPE, "application/octet-stream")
+            .body(body)
             .unwrap();
+        future::ok::<_, Error>(response)
+    });
 
-        let send = respond.send_response(response, false).unwrap();
+    http.serve_connection(socket, service)
-        let data = vec![65u8; 1024*1024];
+        .map_err(Error::from)
-        PipeToSendStream::new(bytes::Bytes::from(data), send).await?;
+        .await?;
-        println!("DATA SENT");
-    }
 
+    println!("H2 connection CLOSE !");
     Ok(())
 }

examples/upload-speed.rs

@@ -1,6 +1,6 @@
 use anyhow::{Error};
 
-use proxmox_backup::api2::types::Userid;
+use proxmox_backup::api2::types::Authid;
 use proxmox_backup::client::*;
 
 async fn upload_speed() -> Result<f64, Error> {
@@ -8,13 +8,13 @@ async fn upload_speed() -> Result<f64, Error> {
     let host = "localhost";
     let datastore = "store2";
 
-    let username = Userid::root_userid();
+    let auth_id = Authid::root_auth_id();
 
-    let options = HttpClientOptions::new()
+    let options = HttpClientOptions::default()
         .interactive(true)
         .ticket_cache(true);
 
-    let client = HttpClient::new(host, 8007, username, options)?;
+    let client = HttpClient::new(host, 8007, auth_id, options)?;
 
     let backup_time = proxmox::tools::time::epoch_i64();
 

src/api2.rs

@@ -1,3 +1,5 @@
+//! The Proxmox Backup Server API
+
 pub mod access;
 pub mod admin;
 pub mod backup;
@@ -7,7 +9,9 @@ pub mod reader;
 pub mod status;
 pub mod types;
 pub mod version;
+pub mod ping;
 pub mod pull;
+pub mod tape;
 mod helpers;
 
 use proxmox::api::router::SubdirMap;
@@ -16,15 +20,17 @@ use proxmox::list_subdirs_api_method;
 
 const NODES_ROUTER: Router = Router::new().match_all("node", &node::ROUTER);
 
-pub const SUBDIRS: SubdirMap = &[
+const SUBDIRS: SubdirMap = &[
     ("access", &access::ROUTER),
     ("admin", &admin::ROUTER),
     ("backup", &backup::ROUTER),
     ("config", &config::ROUTER),
     ("nodes", &NODES_ROUTER),
+    ("ping", &ping::ROUTER),
     ("pull", &pull::ROUTER),
     ("reader", &reader::ROUTER),
     ("status", &status::ROUTER),
+    ("tape", &tape::ROUTER),
     ("version", &version::ROUTER),
 ];
 

src/api2/access.rs

@@ -1,45 +1,69 @@
+//! Access control (Users, Permissions and Authentication)
+
 use anyhow::{bail, format_err, Error};
 
 use serde_json::{json, Value};
+use std::collections::HashMap;
+use std::collections::HashSet;
 
-use proxmox::api::{api, RpcEnvironment, Permission};
 use proxmox::api::router::{Router, SubdirMap};
-use proxmox::{sortable, identity};
+use proxmox::api::{api, Permission, RpcEnvironment};
 use proxmox::{http_err, list_subdirs_api_method};
+use proxmox::{identity, sortable};
 
-use crate::tools::ticket::{self, Empty, Ticket};
-use crate::auth_helpers::*;
 use crate::api2::types::*;
+use crate::auth_helpers::*;
+use crate::server::ticket::ApiTicket;
+use crate::tools::ticket::{self, Empty, Ticket};
 
+use crate::config::acl as acl_config;
+use crate::config::acl::{PRIVILEGES, PRIV_PERMISSIONS_MODIFY, PRIV_SYS_AUDIT};
 use crate::config::cached_user_info::CachedUserInfo;
-use crate::config::acl::{PRIVILEGES, PRIV_PERMISSIONS_MODIFY};
+use crate::config::tfa::TfaChallenge;
 
-pub mod user;
-pub mod domain;
 pub mod acl;
+pub mod domain;
 pub mod role;
+pub mod tfa;
+pub mod user;
+
+#[allow(clippy::large_enum_variant)]
+enum AuthResult {
+    /// Successful authentication which does not require a new ticket.
+    Success,
+
+    /// Successful authentication which requires a ticket to be created.
+    CreateTicket,
+
+    /// A partial ticket which requires a 2nd factor will be created.
+    Partial(TfaChallenge),
+}
 
-/// 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> {
+    tfa_challenge: Option<String>,
+) -> Result<AuthResult, Error> {
     let user_info = CachedUserInfo::new()?;
 
-    if !user_info.is_active_user(&userid) {
+    let auth_id = Authid::from(userid.clone());
+    if !user_info.is_active_auth_id(&auth_id) {
         bail!("user account disabled or expired.");
     }
 
+    if let Some(tfa_challenge) = tfa_challenge {
+        return authenticate_2nd(userid, &tfa_challenge, password);
+    }
+
     if password.starts_with("PBS:") {
         if let Ok(ticket_userid) = Ticket::<Userid>::parse(password)
             .and_then(|ticket| ticket.verify(public_auth_key(), "PBS", None))
         {
             if *userid == ticket_userid {
-                return Ok(true);
+                return Ok(AuthResult::CreateTicket);
             }
             bail!("ticket login failed - wrong userid");
         }
@@ -49,17 +73,17 @@ fn authenticate_user(
         }
 
         let path = path.ok_or_else(|| format_err!("missing path for termproxy ticket"))?;
-        let privilege_name = privs
+        let privilege_name =
-            .ok_or_else(|| format_err!("missing privilege name for termproxy ticket"))?;
+            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)
+        if let Ok(Empty) = Ticket::parse(password).and_then(|ticket| {
-            .and_then(|ticket| ticket.verify(
+            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();
@@ -68,9 +92,8 @@ fn authenticate_user(
                             path_vec.push(part);
                         }
                     }
-
+                    user_info.check_privs(&auth_id, &path_vec, *privilege, false)?;
-                    user_info.check_privs(userid, &path_vec, *privilege, false)?;
+                    return Ok(AuthResult::Success);
-                    return Ok(false);
                 }
             }
 
@@ -78,8 +101,26 @@ fn authenticate_user(
         }
     }
 
-    let _ = crate::auth::authenticate_user(userid, password)?;
+    let _: () = crate::auth::authenticate_user(userid, password)?;
-    Ok(true)
+
+    Ok(match crate::config::tfa::login_challenge(userid)? {
+        None => AuthResult::CreateTicket,
+        Some(challenge) => AuthResult::Partial(challenge),
+    })
+}
+
+fn authenticate_2nd(
+    userid: &Userid,
+    challenge_ticket: &str,
+    response: &str,
+) -> Result<AuthResult, Error> {
+    let challenge: TfaChallenge = Ticket::<ApiTicket>::parse(&challenge_ticket)?
+        .verify_with_time_frame(public_auth_key(), "PBS", Some(userid.as_str()), -60..600)?
+        .require_partial()?;
+
+    let _: () = crate::config::tfa::verify_challenge(userid, &challenge, response.parse()?)?;
+
+    Ok(AuthResult::CreateTicket)
 }
 
 #[api(
@@ -106,6 +147,11 @@ fn authenticate_user(
                 description: "Port for verifying terminal tickets.",
                 optional: true,
             },
+            "tfa-challenge": {
+                type: String,
+                description: "The signed TFA challenge string the user wants to respond to.",
+                optional: true,
+            },
         },
     },
     returns: {
@@ -120,7 +166,9 @@ fn authenticate_user(
             },
             CSRFPreventionToken: {
                 type: String,
-                description: "Cross Site Request Forgery Prevention Token.",
+                description:
+                    "Cross Site Request Forgery Prevention Token. \
+                     For partial tickets this is the string \"invalid\".",
             },
         },
     },
@@ -132,20 +180,24 @@ fn authenticate_user(
 /// Create or verify authentication ticket.
 ///
 /// Returns: An authentication ticket with additional infos.
-fn create_ticket(
+pub fn create_ticket(
     username: Userid,
     password: String,
     path: Option<String>,
     privs: Option<String>,
     port: Option<u16>,
+    tfa_challenge: Option<String>,
+    rpcenv: &mut dyn RpcEnvironment,
 ) -> Result<Value, Error> {
-    match authenticate_user(&username, &password, path, privs, port) {
+    match authenticate_user(&username, &password, path, privs, port, tfa_challenge) {
-        Ok(true) => {
+        Ok(AuthResult::Success) => Ok(json!({ "username": username })),
-            let ticket = Ticket::new("PBS", &username)?.sign(private_auth_key(), None)?;
+        Ok(AuthResult::CreateTicket) => {
-
+            let api_ticket = ApiTicket::full(username.clone());
+            let ticket = Ticket::new("PBS", &api_ticket)?.sign(private_auth_key(), None)?;
             let token = assemble_csrf_prevention_token(csrf_secret(), &username);
 
-            log::info!("successful auth for user '{}'", username);
+            crate::server::rest::auth_logger()?
+                .log(format!("successful auth for user '{}'", username));
 
             Ok(json!({
                 "username": username,
@@ -153,18 +205,38 @@ fn create_ticket(
                 "CSRFPreventionToken": token,
             }))
         }
-        Ok(false) => Ok(json!({
+        Ok(AuthResult::Partial(challenge)) => {
-            "username": username,
+            let api_ticket = ApiTicket::partial(challenge);
-        })),
+            let ticket = Ticket::new("PBS", &api_ticket)?
+                .sign(private_auth_key(), Some(username.as_str()))?;
+            Ok(json!({
+                "username": username,
+                "ticket": ticket,
+                "CSRFPreventionToken": "invalid",
+            }))
+        }
         Err(err) => {
-            let client_ip = "unknown"; // $rpcenv->get_client_ip() || '';
+            let client_ip = match rpcenv.get_client_ip().map(|addr| addr.ip()) {
-            log::error!("authentication failure; rhost={} user={} msg={}", client_ip, username, err.to_string());
+                Some(ip) => format!("{}", ip),
+                None => "unknown".into(),
+            };
+
+            let msg = format!(
+                "authentication failure; rhost={} user={} msg={}",
+                client_ip,
+                username,
+                err.to_string()
+            );
+            crate::server::rest::auth_logger()?.log(&msg);
+            log::error!("{}", msg);
+
             Err(http_err!(UNAUTHORIZED, "permission check failed."))
         }
     }
 }
 
 #[api(
+    protected: true,
     input: {
         properties: {
             userid: {
@@ -176,35 +248,42 @@ fn create_ticket(
         },
     },
     access: {
-        description: "Anybody is allowed to change there own password. In addition, users with 'Permissions:Modify' privilege may change any password.",
+        description: "Everybody is allowed to change their own password. In addition, users with 'Permissions:Modify' privilege may change any password on @pbs realm.",
         permission: &Permission::Anybody,
     },
-
 )]
 /// Change user password
 ///
 /// Each user is allowed to change his own password. Superuser
 /// can change all passwords.
-fn change_password(
+pub fn change_password(
     userid: Userid,
     password: String,
     rpcenv: &mut dyn RpcEnvironment,
 ) -> Result<Value, Error> {
-
+    let current_auth: Authid = rpcenv
-    let current_user: Userid = rpcenv
+        .get_auth_id()
-        .get_user()
+        .ok_or_else(|| format_err!("no authid available"))?
-        .ok_or_else(|| format_err!("unknown user"))?
         .parse()?;
 
-    let mut allowed = userid == current_user;
+    if current_auth.is_token() {
+        bail!("API tokens cannot access this API endpoint");
+    }
 
-    if userid == "root@pam" { allowed = true; }
+    let current_user = current_auth.user();
+
+    let mut allowed = userid == *current_user;
 
     if !allowed {
         let user_info = CachedUserInfo::new()?;
-        let privs = user_info.lookup_privs(&current_user, &[]);
+        let privs = user_info.lookup_privs(&current_auth, &[]);
-        if (privs & PRIV_PERMISSIONS_MODIFY) != 0 { allowed = true; }
+        if user_info.is_superuser(&current_auth) {
-    }
+            allowed = true;
+        }
+        if (privs & PRIV_PERMISSIONS_MODIFY) != 0 && userid.realm() != "pam" {
+            allowed = true;
+        }
+    };
 
     if !allowed {
         bail!("you are not authorized to change the password.");
@@ -216,20 +295,138 @@ fn change_password(
     Ok(Value::Null)
 }
 
+#[api(
+    input: {
+        properties: {
+            "auth-id": {
+                type: Authid,
+                optional: true,
+            },
+            path: {
+                schema: ACL_PATH_SCHEMA,
+                optional: true,
+            },
+        },
+    },
+    access: {
+        permission: &Permission::Anybody,
+        description: "Requires Sys.Audit on '/access', limited to own privileges otherwise.",
+    },
+    returns: {
+        description: "Map of ACL path to Map of privilege to propagate bit",
+        type: Object,
+        properties: {},
+        additional_properties: true,
+    },
+)]
+/// List permissions of given or currently authenticated user / API token.
+///
+/// Optionally limited to specific path.
+pub fn list_permissions(
+    auth_id: Option<Authid>,
+    path: Option<String>,
+    rpcenv: &dyn RpcEnvironment,
+) -> Result<HashMap<String, HashMap<String, bool>>, Error> {
+    let current_auth_id: Authid = rpcenv.get_auth_id().unwrap().parse()?;
+
+    let user_info = CachedUserInfo::new()?;
+    let user_privs = user_info.lookup_privs(&current_auth_id, &["access"]);
+
+    let auth_id = match auth_id {
+        Some(auth_id) if auth_id == current_auth_id => current_auth_id,
+        Some(auth_id) => {
+            if user_privs & PRIV_SYS_AUDIT != 0 
+                || (auth_id.is_token()
+                    && !current_auth_id.is_token()
+                    && auth_id.user() == current_auth_id.user())
+            {
+                auth_id
+            } else {
+                bail!("not allowed to list permissions of {}", auth_id);
+            }
+        },
+        None => current_auth_id,
+    };
+
+    fn populate_acl_paths(
+        mut paths: HashSet<String>,
+        node: acl_config::AclTreeNode,
+        path: &str,
+    ) -> HashSet<String> {
+        for (sub_path, child_node) in node.children {
+            let sub_path = format!("{}/{}", path, &sub_path);
+            paths = populate_acl_paths(paths, child_node, &sub_path);
+            paths.insert(sub_path);
+        }
+        paths
+    }
+
+    let paths = match path {
+        Some(path) => {
+            let mut paths = HashSet::new();
+            paths.insert(path);
+            paths
+        }
+        None => {
+            let mut paths = HashSet::new();
+
+            let (acl_tree, _) = acl_config::config()?;
+            paths = populate_acl_paths(paths, acl_tree.root, "");
+
+            // default paths, returned even if no ACL exists
+            paths.insert("/".to_string());
+            paths.insert("/access".to_string());
+            paths.insert("/datastore".to_string());
+            paths.insert("/remote".to_string());
+            paths.insert("/system".to_string());
+
+            paths
+        }
+    };
+
+    let map = paths.into_iter().fold(
+        HashMap::new(),
+        |mut map: HashMap<String, HashMap<String, bool>>, path: String| {
+            let split_path = acl_config::split_acl_path(path.as_str());
+            let (privs, propagated_privs) = user_info.lookup_privs_details(&auth_id, &split_path);
+
+            match privs {
+                0 => map, // Don't leak ACL paths where we don't have any privileges
+                _ => {
+                    let priv_map =
+                        PRIVILEGES
+                            .iter()
+                            .fold(HashMap::new(), |mut priv_map, (name, value)| {
+                                if value & privs != 0 {
+                                    priv_map
+                                        .insert(name.to_string(), value & propagated_privs != 0);
+                                }
+                                priv_map
+                            });
+
+                    map.insert(path, priv_map);
+                    map
+                }
+            }
+        },
+    );
+
+    Ok(map)
+}
+
 #[sortable]
 const SUBDIRS: SubdirMap = &sorted!([
     ("acl", &acl::ROUTER),
+    ("password", &Router::new().put(&API_METHOD_CHANGE_PASSWORD)),
     (
-        "password", &Router::new()
+        "permissions",
-            .put(&API_METHOD_CHANGE_PASSWORD)
+        &Router::new().get(&API_METHOD_LIST_PERMISSIONS)
-    ),
-    (
-        "ticket", &Router::new()
-            .post(&API_METHOD_CREATE_TICKET)
     ),
+    ("ticket", &Router::new().post(&API_METHOD_CREATE_TICKET)),
     ("domains", &domain::ROUTER),
     ("roles", &role::ROUTER),
     ("users", &user::ROUTER),
+    ("tfa", &tfa::ROUTER),
 ]);
 
 pub const ROUTER: Router = Router::new()

src/api2/access/acl.rs

@@ -1,5 +1,6 @@
+//! Manage Access Control Lists
+
 use anyhow::{bail, Error};
-use ::serde::{Deserialize, Serialize};
 
 use proxmox::api::{api, Router, RpcEnvironment, Permission};
 use proxmox::tools::fs::open_file_locked;
@@ -7,44 +8,30 @@ 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};
-
+use crate::config::cached_user_info::CachedUserInfo;
-#[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,
+    token_user: &Option<Authid>,
 ) {
+    // tokens can't have tokens, so we can early return
+    if let Some(token_user) = token_user {
+        if token_user.is_token() {
+            return;
+        }
+    }
+
     for (user, roles) in &node.users {
+        if let Some(token_user) = token_user {
+            if !user.is_token()
+                || user.user() != token_user.user() {
+                 continue;
+            }
+        }
+
         for (role, propagate) in roles {
             list.push(AclListItem {
                 path: if path.is_empty() { String::from("/") } else { path.to_string() },
@@ -56,6 +43,10 @@ fn extract_acl_node_data(
         }
     }
     for (group, roles) in &node.groups {
+        if token_user.is_some() {
+            continue;
+        }
+
         for (role, propagate) in roles {
             list.push(AclListItem {
                 path: if path.is_empty() { String::from("/") } else { path.to_string() },
@@ -71,7 +62,7 @@ fn extract_acl_node_data(
     }
     for (comp, child) in &node.children {
         let new_path = format!("{}/{}", path, comp);
-        extract_acl_node_data(child, &new_path, list, exact);
+        extract_acl_node_data(child, &new_path, list, exact, token_user);
     }
 }
 
@@ -98,7 +89,8 @@ fn extract_acl_node_data(
         }
     },
     access: {
-        permission: &Permission::Privilege(&["access", "acl"], PRIV_SYS_AUDIT, false),
+        permission: &Permission::Anybody,
+        description: "Returns all ACLs if user has Sys.Audit on '/access/acl', or just the ACLs containing the user's API tokens.",
     },
 )]
 /// Read Access Control List (ACLs).
@@ -107,18 +99,26 @@ pub fn read_acl(
     exact: bool,
     mut rpcenv: &mut dyn RpcEnvironment,
 ) -> Result<Vec<AclListItem>, Error> {
+    let auth_id = rpcenv.get_auth_id().unwrap().parse()?;
 
-    //let auth_user = rpcenv.get_user().unwrap();
+    let user_info = CachedUserInfo::new()?;
+
+    let top_level_privs = user_info.lookup_privs(&auth_id, &["access", "acl"]);
+    let auth_id_filter = if (top_level_privs & PRIV_SYS_AUDIT) == 0 {
+        Some(auth_id)
+    } else {
+        None
+    };
 
     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);
+            extract_acl_node_data(&node, path, &mut list, exact, &auth_id_filter);
         }
     } else {
-        extract_acl_node_data(&tree.root, "", &mut list, exact);
+        extract_acl_node_data(&tree.root, "", &mut list, exact, &auth_id_filter);
     }
 
     rpcenv["digest"] = proxmox::tools::digest_to_hex(&digest).into();
@@ -140,9 +140,9 @@ pub fn read_acl(
                 optional: true,
                 schema: ACL_PROPAGATE_SCHEMA,
             },
-            userid: {
+            "auth-id": {
                 optional: true,
-                type: Userid,
+                type: Authid,
             },
             group: {
                 optional: true,
@@ -160,20 +160,45 @@ pub fn read_acl(
        },
     },
     access: {
-        permission: &Permission::Privilege(&["access", "acl"], PRIV_PERMISSIONS_MODIFY, false),
+        permission: &Permission::Anybody,
+        description: "Requires Permissions.Modify on '/access/acl', limited to updating ACLs of the user's API tokens otherwise."
     },
 )]
 /// Update Access Control List (ACLs).
+#[allow(clippy::too_many_arguments)]
 pub fn update_acl(
     path: String,
     role: String,
     propagate: Option<bool>,
-    userid: Option<Userid>,
+    auth_id: Option<Authid>,
     group: Option<String>,
     delete: Option<bool>,
     digest: Option<String>,
-    _rpcenv: &mut dyn RpcEnvironment,
+    rpcenv: &mut dyn RpcEnvironment,
 ) -> Result<(), Error> {
+    let current_auth_id: Authid = rpcenv.get_auth_id().unwrap().parse()?;
+
+    let user_info = CachedUserInfo::new()?;
+
+    let top_level_privs = user_info.lookup_privs(&current_auth_id, &["access", "acl"]);
+    if top_level_privs & PRIV_PERMISSIONS_MODIFY == 0 {
+        if group.is_some() {
+            bail!("Unprivileged users are not allowed to create group ACL item.");
+        }
+
+        match &auth_id {
+            Some(auth_id) => {
+                if current_auth_id.is_token() {
+                    bail!("Unprivileged API tokens can't set ACL items.");
+                } else if !auth_id.is_token() {
+                    bail!("Unprivileged users can only set ACL items for API tokens.");
+                } else if auth_id.user() != current_auth_id.user() {
+                    bail!("Unprivileged users can only set ACL items for their own API tokens.");
+                }
+            },
+            None => { bail!("Unprivileged user needs to provide auth_id to update ACL item."); },
+        };
+    }
 
     let _lock = open_file_locked(acl::ACL_CFG_LOCKFILE, std::time::Duration::new(10, 0), true)?;
 
@@ -190,11 +215,12 @@ pub fn update_acl(
 
     if let Some(ref _group) = group {
         bail!("parameter 'group' - groups are currently not supported.");
-    } else if let Some(ref userid) = userid {
+    } else if let Some(ref auth_id) = auth_id {
         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() {
+            if user_cfg.sections.get(&auth_id.to_string()).is_none() {
-                bail!("no such user.");
+                bail!(format!("no such {}.",
+                              if auth_id.is_token() { "API token" } else { "user" }));
             }
         }
     } else {
@@ -205,11 +231,11 @@ pub fn update_acl(
         acl::check_acl_path(&path)?;
     }
 
-    if let Some(userid) = userid {
+    if let Some(auth_id) = auth_id {
         if delete {
-            tree.delete_user_role(&path, &userid, &role);
+            tree.delete_user_role(&path, &auth_id, &role);
         } else {
-            tree.insert_user_role(&path, &userid, &role, propagate);
+            tree.insert_user_role(&path, &auth_id, &role, propagate);
         }
     } else if let Some(group) = group {
         if delete {

src/api2/access/domain.rs

@@ -1,3 +1,5 @@
+//! List Authentication domains/realms
+
 use anyhow::{Error};
 
 use serde_json::{json, Value};

src/api2/access/role.rs

@@ -1,3 +1,5 @@
+//! Manage Roles with privileges
+
 use anyhow::Error;
 
 use serde_json::{json, Value};
@@ -46,7 +48,7 @@ fn list_roles() -> Result<Value, Error> {
         let mut priv_list = Vec::new();
         for (name, privilege) in PRIVILEGES.iter() {
             if privs & privilege > 0 {
-                priv_list.push(name.clone());
+                priv_list.push(name);
             }
         }
         list.push(json!({ "roleid": role, "privs": priv_list, "comment": comment }));