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 A2943EEF5 for ; Tue, 13 Dec 2022 15:18:05 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 874F120859 for ; Tue, 13 Dec 2022 15:18:05 +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 ; Tue, 13 Dec 2022 15:18:03 +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 6B66C43D36 for ; Tue, 13 Dec 2022 15:18:03 +0100 (CET) From: Noel Ullreich To: pve-devel@lists.proxmox.com Date: Tue, 13 Dec 2022 15:17:54 +0100 Message-Id: <20221213141754.101172-1-n.ullreich@proxmox.com> X-Mailer: git-send-email 2.30.2 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.070 Adjusted score from AWL reputation of From: address 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 Alignment POISEN_SPAM_PILL 0.1 Meta: its spam POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pve-devel] [PATCH pve-docs] updated tags docs 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: Tue, 13 Dec 2022 14:18:05 -0000 updated the tags doc with slight rephrasing, corrected grammar, and fixed typos. Signed-off-by: Noel Ullreich --- datacenter.cfg.5-opts.adoc | 2 +- pve-gui.adoc | 70 ++++++++++++++++++-------------------- 2 files changed, 35 insertions(+), 37 deletions(-) diff --git a/datacenter.cfg.5-opts.adoc b/datacenter.cfg.5-opts.adoc index 6e53e1c..7f96388 100644 --- a/datacenter.cfg.5-opts.adoc +++ b/datacenter.cfg.5-opts.adoc @@ -146,7 +146,7 @@ Privilege options for user-settable tags `user-allow`=`` ('default =' `free`);; -Controls which tags can be set or deleted on resources a user controls (such as guests). Users with the `Sys.Modify` privilege on `/` are always unrestricted. 'none' no tags are usable. 'list' tags from 'user-allow-list' are usable. 'existing' like list, but already existing tags of resources are also usable.'free' no tag restrictions. +Controls which tags can be set or deleted on resources a user controls (such as guests). Users with the `Sys.Modify` privilege on `/` are always unrestricted. 'none' no tags are usable. 'list' tags from 'user-allow-list' are usable. 'existing' like list, but already existing tags of resources are also usable. 'free' no tag restrictions. `user-allow-list`=`[;...]` ;; diff --git a/pve-gui.adoc b/pve-gui.adoc index ff95cfb..d6d9426 100644 --- a/pve-gui.adoc +++ b/pve-gui.adoc @@ -386,68 +386,66 @@ 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. +For organizational purposes, it is possible to set `tags` for guests. +Currently, these only provide informational value to users. +Tags are displayed in two places in the web interface: in the `Resource Tree` and +in the status line when a guest ist 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. +Tags can be added, edited, and removed in the status line of the guest by +clicking on the `pencil` icon. You can add multiple tags by pressing the `+` +button and remove them by pressing the `-` button and save or cancel the changes +with the `checkmark` and `x` button respectively. -The tags can also be set via the CLI, where multiple tags are semi-colon -separated, for example: +Tags can also be set via the CLI, where multiple tags are separated by semicolons. +For example: ---- # qm set ID --tags myfirsttag;mysecondtag ---- -Styling -~~~~~~~ +Style Configuration +~~~~~~~~~~~~~~~~~~~ [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: +By default, the tag colors are derived from their text in a deterministic way. +The color, shape in the resource tree, and case-sensitivity, as well as how tags +are sorted, can be customized. This can be done via the web interface under +__Datacenter -> Options -> Tag Style Override__. Alternatively, this can be done +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 +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: +can set any tags they want (see +xref:pveum_permission_management[Permission Management]). Under __Datacenter -> +Options -> User Tag Access__ permissions for tag access can be set: + +* `free`: users are not restricted in setting tags (Default) +* `list`: users can set tags based on a predefined list of tags +* `existing`: like list but users can also use already existing tags +* `none`: users are restricted from using tags + +The same can also be done via the CLI. -* a list of allowed tags -* existing tags -* no tags at all +Note that a user with the `Sys.Modify` privileges 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 can only be added and removed by +users with the privilege `Sys.Modify` on `/`. The list of registered tags be +edited under __Datacenter -> Options -> Registered Tags__ or via the CLI. -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 +For more details on the exact options and how to invoke them in the CLI, see xref:datacenter_configuration_file[Datacenter Configuration]. ifdef::wiki[] -- 2.30.2