conf: add support for a dark mode in the documentation

this commit adds support for a dark theme that behaves similarly to
that one used by the api viewer.

Signed-off-by: Stefan Sterz <s.sterz@proxmox.com>

pveproxy: add some explicit references

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

qm: guest trim: add note mentioning issue with ext4

It is rather unexpected and seems worth mentioning. Reported in the
community forum [0] and the explanation found by Alwin [1].

[0]: https://forum.proxmox.com/threads/123819/
[1]: https://serverfault.com/questions/1113127/fstrim-is-very-slow-on-xfs-and-always-return-same-value-unlike-ext4/1113129#1113129

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

docs: add dark mode support to the api viewer

adds dark mode support to the api viewer that is activated depending
on the users theme preference. similar to the main gui's "auto"
theme.

this requires a bumps of the widget toolkit so the loaded css file is
present

Signed-off-by: Stefan Sterz <s.sterz@proxmox.com>

track pvescheduler.8-synopsis.adoc

it was never committed, but needs to be, else there's effectively a build-dep
cycle between pve-docs and pve-manager..

Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>

qm: emulated devices: make recommendation for virtio devices more visible

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

qm: emulated devices: mention that virtio devices are better maintained

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

qm: hard disk controllers: recommend VirtIO controllers

Quoting from [0]:
> In general, I advise against using AHCI in production as better
> performance (and dev support) can be achieved through virtio.

[0]: https://lists.nongnu.org/archive/html/qemu-devel/2023-02/msg03915.html

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

qm: hard disk controllers: reword and update section

Most importantly, mention that VirtIO SCSI single in combination with
IO thread is the new recommendation and default. The controller type
used for the QEMU commandline is still the same (but one for each
disk), so information about when OSes started supporting it should be
accurate.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

node: record todo in comment

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

fix #4194: clarify that its a bulk shutdown, not immediate hard stop

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

pveum: remove `auth` part from Keycloak issuer URL

Keycloak seems to have dropped the `auth` part with their 18.0
release.

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

access control: remove misleading 'additionally' in perm-modify description

'additionally' in this context is a bit misleading, as it suggests
that e.g. 'VM.Allocate' AND 'Permissions.Modify' are needed, conflicting
with the previous paragraph.

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

installation: drop dead link to spanish youtube channel

Reported-by: Daniela Häsler <daniela@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

cluster join: mention that storage config from cluster is inherited

and what to do about it. It's a rather common topic in forum threads.

Suggested in the community forum:
https://forum.proxmox.com/threads/118492/post-513743

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

qm: fix two grammar issues

Fixed two small grammar errors in the qm chapter. Rephrased a
sentence before the fixed sentence so that it would be more legible.

Signed-off-by: Noel Ullreich <n.ullreich@proxmox.com>
 [ T: resolve context merge conflict on current master ]
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

attrs: update cephdocs template to quincy

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

whitespace fixup

docs: rename "dirs" parameter, clarify paths

Chagne the name of the "dirs" parameter to "content-dirs" and be less
misleading with "absolute paths".

Signed-off-by: Leo Nunner <l.nunner@proxmox.com>

docs: document 'dirs' parameter for directory storage

Signed-off-by: Leo Nunner <l.nunner@proxmox.com>

asciidoc-pve: small code/style cleanups

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

qm: IO-Thread: rework and add a bit more context

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

qm: IO thread: mention that setting can also help with hangs

See https://bugzilla.kernel.org/show_bug.cgi?id=199727

Reported-by: Roland Kletzing <devzero@web.de>
Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

qm: IO thread: be more precise about how QEMU handles IO

Reported in the community forum[0].

The setting can already help with a single disk. Without the option,
there is not one IO thread as the old wording suggested, but IO is
handled in the main event loop or vCPU threads (see the kvm man page).

[0]: https://forum.proxmox.com/threads/118390/post-518532

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

fix #4422: correct hdiutil parameter order

the input file has to come as first positional argument.

Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>

tree-wide: switch to offical spelling of QEMU

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

storage: iscsi direct: update information about packages

As reported in the community forum [0], libiscsi-bin is required. The
library package on Bullseye would be libiscsi7, but there is no real
need to mention the package explicitly, because it is a dependency of
both, libiscsi-bin and pve-qemu-kvm.

[0]: https://forum.proxmox.com/threads/119369

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

install: update wiki link for debian bullseye guide

Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>

intro: add some references

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

bump version to 7.3-1

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

ha: crs: clarify that non-HA-managed services are currently not counted

Without explicitly stating this, it's rather easily missed.

Reported-by: Dominik Csapak <d.csapak@proxmox.com>
Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

ha: crs: fix typo

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

update static/schema information

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

ha: crs: remove outdated comment about restarting service

Commit 086f707 ("manager: update crs scheduling mode once per round")
in pve-ha-manager made it obsolete. Mention that a change will be
effective with the next round instead.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

sysadmin network: document disabling mac-learning on a bridge

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

sysadmin zfs: document pool naming rules

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

bump version to 7.2-5

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

ha crs: add reference for online help

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

gui: document tags with screenshots

and list some examples

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
 [ T: commit screen shots ]
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

gui: document tags with screenshots

and list some examples

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>

ha: fix section levels for crs sub-sections

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

ha crs: split tech-preview and many-service warning into two

And reduce the level from warning to important, as the warning symbol
is a "stop hand" which is rather too discouraging for readers.

rename section to Cluster Resource Scheduling

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

ha: add warning against using 'static' mode with many services

In HA manager, the function recompute_online_node_usage() is called
very often currently and the 'static' mode needs to read the guest
configs which adds a bit of overhead.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

ha: add section about scheduler modes

briefly describing the 'basic' and 'static' modes and with a note
mentioning plans for balancers.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

qm: use monospace for mtu=1

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

qm: add documentation for vm network MTU setting

Signed-off-by: Daniel Tschlatscher <d.tschlatscher@proxmox.com>

bibliography: update debian handbook meta info

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

Update ExtJS version

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>

local-zfs: typo fix/better phrasing

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>

local-zfs: rephrase ZFS RAID description

I tried to make the performance impact clearer, as what "behave like a number of disks"
actually means wasn't quite clear to me.

Use "in regard to" rather than "in regard of", as I couldn't find
any source that this phrase is (commonly) used in modern english.

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>

local-zfs Remove SSD suggestion as it's outdated

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>

local-lvm: typo fix/better phrasing

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>

network: fix dead link

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>

network: fix typo

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>

package-repos: fix typos

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>

bibliography: update 404 link

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>

pci passthrough: rework IOMMU sections a bit

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

pci passthrough: drop iommu.passthrough=1 kernel cmd opt, only for ARM

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

pcie-passthrough: add short note about iommu passthrough mode

that explains in one sentence what it does, that it can increase
performance and how to activate it.

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>

pcie-passthrough: note that iommu activation is not always necessary

especially on newer kernels

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>

fix #4319: use corred port range for corosync v3.x

corosync v2 used ports 5405 and 5404, but corosync v3 uses ports 5405-5412.

Signed-off-by: Marco Gabriel <mgabriel@inett.de>

bump version to 7.2-4

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

update static/schema information

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

fix #3967: add ZFS dRAID documentation

add some basic explanation how ZFS dRAID works including
links to openZFS for more details

add documentation for two dRAID parameters used in code

Signed-off-by: Stefan Hrdlicka <s.hrdlicka@proxmox.com>

Document VM.Config.Cloudinit permission

Signed-off-by: Leo Nunner <l.nunner@proxmox.com>

cloud init: use 'import-from' disk syntax to avoid a step

Put the 'scsihw' part into the previous command, so that the rather
complicated import command can stand on its own.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

cloud init: use expected disk number in example

Starting from a storage with no disks for the VM ID in question, the
imported disk will be called vm-9000-disk-0.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

cloud init: use 'order' variant for 'boot' property

instead of the legacy 'boot: c'+bootdisk combination.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

bump version to 7.2-3

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

asciidoc-pve: disallow certain characters in onlineHelp keys

this removes the lazily evaluated part of the regex used to detect
`onlineHelp` keys in order to match them with asciidoc anchors in the
documentation. it uses a pattern that excludes curly braces, brackets
and quotations instead. this allows for greedy matching and also
removes an issue where keys that are set via CBind were included
incorrectly. the script would try to find an anchor name that was
equivalent to the CBind placeholder, which would fail.

since brackets, curly braces and quotation marks aren't allowed in
asciidoc anchors anyway, excluding them like this should be safe.

Signed-off-by: Stefan Sterz <s.sterz@proxmox.com>

update static/schema information

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

pveum: add the "user_mgmt" reference to the documentation

since this key was missing from the PVE documentation, the TFA ui's
help buttons didn't work as they relied on it.

Signed-off-by: Stefan Sterz <s.sterz@proxmox.com>

Merge branch 'taskset' into taskset-merged

fix #3593: add affinity to docs

Added affinity to the resource limiting info in qm.adoc.
Added affinity to the qemu conf spec in qm.conf.5-opts.adoc.

Signed-off-by: Daniel Bowder <daniel@bowdernet.com>

update link to debian handbook to avoid 404

seems like Bullseye is not yet ready, so the download for current
stable is 404, link to general "get book" page, which also provides a
donation option and so better for the project.

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

it's -> its because it isn't 'it is'

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

installations: various typo/grammar fixes

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

installation: note that some ISO grub options moved to sub menu

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

installation: add note that secure boot currently needs to be disabled

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

consistently capitalize Ceph

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

ceph: remove misplaced comma

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

consistently use 'web interface' (two words)

Signed-off-by: Matthias Heiserer <m.heiserer@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>

firewall: fix typo: ident -> identical

"the following two are ident" --> "the following two are identical"

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>

asciidoc: fix capitalization of GmbH

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>

qm: avoid using "e.g."

favor "for example", "such as" or "like", as our technical writing
guide forbids using "e.g." in the docs where possible.

Also do some small fixes in the vicinity while at it.

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

qm: rework migration sections, drop mentioning outdated limitations

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

pveum: mention Sys.Incoming privilege

Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>

updated copyright to current year

Updated the copyright in `pve-copyright.adoc` which is used to generate the man pages.
Pervious version was from 2019

Signed-off-by: Noel Ullreich <n.ullreich@proxmox.com>

fix #4307: installation: correct typos in prepare macOS medium section

It seems `bs=1m` needs to be `bs=1M` in apple world. Correctly refer
to `.dmg` not `.img` and reword slightly.

Also, while at it, order the `bs=1M` in the middle, making the target
of more accessible for editing after copy + paste.

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

pvesr: remove note about offline migration

It has been possible since quite a while to live migrate replicated
guests.

Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>

pct/qm: update cpuunits default

which is 100 on hosts running cgroup v2. Still mention the old default
relevant for hosts with legacy cgroups.

Also reword the sentence with "gets in regards to other VMs running"
which sounded a bit off.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

qm: resource limits: update systemd setting name for cpuunits

As mentioned in man 5 systemd.resource-control, the CPUShares setting
was replaced by CPUWeight and is deprecated.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

backup: mention max-workers performance setting

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

backup: merge sections describing jobs

keeping a short intro referring to the full section at the beginning.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

backup: expand section for jobs

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

backup: rework storage section, mentioning and recommending PBS

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

backup: fix title case and add skelleton for new jobs section

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

cloud init: mention that serial display might not work for all images

Example from the community forum:
https://forum.proxmox.com/threads/112225/

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

cloud init: add warning to not install cloud-init on the host

From time to time, users install the cloud-init package on the host
by accident [0]. Since the other commands are intended to be run on
the host, add a warning about the one command that shouldn't.

Patch suggested by @Neobin on the community forum [1].

[0] https://forum.proxmox.com/threads/115530/post-499610
[1] https://forum.proxmox.com/threads/115530/post-499624

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>

zfs: special device: update maximum for special_small_blocks

In ZFS 0.8.3, the limit was increased to 1M [0][1].

[0] https://github.com/openzfs/zfs/releases/tag/zfs-0.8.3
[1] https://github.com/openzfs/zfs/pull/9355

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>