From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 073FD9B06 for ; Fri, 18 Nov 2022 12:29:55 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id D4A2C37CEE for ; Fri, 18 Nov 2022 12:29:24 +0100 (CET) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [94.136.29.106]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS for ; Fri, 18 Nov 2022 12:29:24 +0100 (CET) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id C3F9044C0D for ; Fri, 18 Nov 2022 12:29:23 +0100 (CET) From: Dominik Csapak To: pve-devel@lists.proxmox.com Date: Fri, 18 Nov 2022 12:29:22 +0100 Message-Id: <20221118112922.2206811-1-d.csapak@proxmox.com> X-Mailer: git-send-email 2.30.2 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: =?UTF-8?Q?0=0A=09?=AWL -0.085 Adjusted score from AWL reputation of From: =?UTF-8?Q?address=0A=09?=BAYES_00 -1.9 Bayes spam probability is 0 to 1% KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict =?UTF-8?Q?Alignment=0A=09?=POISEN_SPAM_PILL 0.1 Meta: its =?UTF-8?Q?spam=0A=09?=POISEN_SPAM_PILL_1 0.1 random spam to be learned in =?UTF-8?Q?bayes=0A=09?=POISEN_SPAM_PILL_3 0.1 random spam to be learned in =?UTF-8?Q?bayes=0A=09?=SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF =?UTF-8?Q?Record=0A=09?=SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pve-devel] [PATCH docs] gui: document tags with screenshots X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 18 Nov 2022 11:29:55 -0000 and list some examples Signed-off-by: Dominik Csapak --- was a bit restricted by the space for screenshots, so i only really could add three here. when i added more i couldn't get the spacing right. also needs the screenshots applied to the repo to be buildable @thomas will do that pve-gui.adoc | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/pve-gui.adoc b/pve-gui.adoc index 3fee2e0..4d3465f 100644 --- a/pve-gui.adoc +++ b/pve-gui.adoc @@ -381,6 +381,75 @@ and the corresponding interfaces for each menu item on the right. * *Permissions:* manage the permissions for the pool. +Tags +---- + +[thumbnail="screenshot/gui-qemu-summary-tags-edit.png", float="left"] + +For organizational purposes, it is possible to set `tags` on guests. These have +currently only informational value and they are display by default in the gui +in two places, the `Resource Tree` and in the status line when a guest is +selected. + +They can be added, edited and removed in that status line of the guest by +clicking on the `pencil` icon. After the tags have the desired values, you +can click on the `check mark` button to apply the changes, or click the +`X` button to cancel you editing. + +The tags can also be set via the CLI, where multiple tags are semi-colon +separated, for example: + +---- +# qm set ID --tags myfirsttag;mysecondtag +---- + +Styling +~~~~~~~ + +[thumbnail="screenshot/gui-datacenter-tag-style.png"] + +To adapt to various use cases and preferences, there are some options in the +datacenter configuration that helps an admin control the behaviour and style +of tags, such as the colors, ordering, and basic permission settings. + + +By default the tag colors are derived from their text in a deterministic way, +but can be overridden in the datacenter configuration (The background color as +well as the text color) as hexadecimal RGB values. You can also set these +overrides via the CLI, for example: + +---- +# pvesh set /cluster/options --tag-style color-map=example:000000:FFFFFF +---- + +Sets the background color of the tag `example` to black (#000000) and the text +color to white (#FFFFFF). + +You can also change the style of the tags in the tree and if the tags should +be alphabetically sorted (the default) or should retain their order from the +guest configuration. + +Permissions +~~~~~~~~~~~ + +[thumbnail="screenshot/gui-datacenter-options.png"] + +By default, users with the privilege `VM.Config.Options` on a guest (`/vms/ID`) +can set any tags they want. If you want to restrict this behaviour, it is +possible to set various modes via the datacenter configuration: + +* a list of allowed tags +* existing tags +* no tags at all + +Note that a user with `Sys.Modify` on `/` is always able to set or delete +any tags, regardless of the settings here. Additionally, there is a configurable +list of `registered tags` which will also require the privilege `Sys.Modify` +on `/` to be added or removed independent of the mode. + +For more details on the exact options, see the +xref:datacenter_configuration_file[Datacenter Configuration]. + ifdef::wiki[] See Also -- 2.30.2