* Two-Factor Authentication (OATH, Yubikey)
-* Based on ExtJS 6.x JavaScript framework
+* Based on ExtJS 7.x JavaScript framework
+
+
+Login
+-----
+
+[thumbnail="screenshot/gui-login-window.png"]
+
+When you connect to the server, you will first see the login window.
+{pve} supports various authentication backends ('Realm'), and
+you can select the language here. The GUI is translated to more
+than 20 languages.
+
+NOTE: You can save the user name on the client side by selecting the
+checkbox at the bottom. This saves some typing when you login next
+time.
GUI Overview
------------
-[thumbnail="gui-datacenter-summary.png"]
+[thumbnail="screenshot/gui-datacenter-summary.png"]
+
+The {pve} user interface consists of four regions.
+
+[horizontal]
+
+Header:: On top. Shows status information and contains buttons for
+most important actions.
+
+Resource Tree:: At the left side. A navigation tree where you can select
+specific objects.
+
+Content Panel:: Center region. Selected objects display configuration
+options and status here.
+
+Log Panel:: At the bottom. Displays log entries for recent tasks. You
+can double-click on those log entries to get more details, or to abort
+a running task.
+
+NOTE: You can shrink and expand the size of the resource tree and log
+panel, or completely hide the log panel. This can be helpful when you
+work on small displays and want more space to view other content.
+
+
+Header
+~~~~~~
+
+On the top left side, the first thing you see is the Proxmox
+logo. Next to it is the current running version of {pve}. In the
+search bar nearside you can search for specific objects (VMs,
+containers, nodes, ...). This is sometimes faster than selecting an
+object in the resource tree.
+
+The right part of the header contains four buttons:
+
+[horizontal]
+Documentation :: Opens a new browser window showing the reference documentation.
+
+Create VM :: Opens the virtual machine creation wizard.
+
+Create CT :: Open the container creation wizard.
+
+User Menu :: Displays the identity of the user you're currently logged in
+with, and clicking it opens a menu with user-specific options.
++
+In the user menu, you'll find the 'My Settings' dialog, which provides local UI
+settings. Below that, there are shortcuts for 'TFA' (Two-Factor Authentication)
+and 'Password' self-service. You'll also find options to change the 'Language'
+and the 'Color Theme.' Finally, at the bottom of the menu is the 'Logout'
+option.
+
+
+[[gui_my_settings]]
+My Settings
+~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-my-settings.png"]
+
+The 'My Settings' window allows you to set locally stored settings. These
+include the 'Dashboard Storages' which allow you to enable or disable specific
+storages to be counted towards the total amount visible in the datacenter
+summary. If no storage is checked the total is the sum of all storages, same
+as enabling every single one.
+
+Below the dashboard settings you find the stored user name and a button to
+clear it as well as a button to reset every layout in the GUI to its default.
+
+On the right side there are 'xterm.js Settings'. These contain the following
+options:
+
+[horizontal]
+Font-Family :: The font to be used in xterm.js (e.g. Arial).
+
+Font-Size :: The preferred font size to be used.
+
+Letter Spacing :: Increases or decreases spacing between letters in text.
+
+Line Height :: Specify the absolute height of a line.
+
+
+
+Resource Tree
+~~~~~~~~~~~~~
+
+This is the main navigation tree. On top of the tree you can select
+some predefined views, which change the structure of the tree
+below. The default view is the *Server View*, and it shows the following
+object types:
+
+[horizontal]
+Datacenter:: Contains cluster-wide settings (relevant for all nodes).
+
+Node:: Represents the hosts inside a cluster, where the guests run.
+
+Guest:: VMs, containers and templates.
+
+Storage:: Data Storage.
+
+Pool:: It is possible to group guests using a pool to simplify
+management.
+
+
+The following view types are available:
+
+[horizontal]
+Server View:: Shows all kinds of objects, grouped by nodes.
+
+Folder View:: Shows all kinds of objects, grouped by object type.
-Lets start with the header.
-We start on the left side, where the first thing you see is the Proxmox Logo.
-Next to it is the current running version of Proxmox VE.
-In the search bar it is possible to search for item which the datacenter contains.
-After the search-bar the identity is shown (login name).
+Pool View:: Show VMs and containers, grouped by pool.
-[thumbnail="gui-my-settings.png"]
-The 'my settings' button (Gear Symble) contains dashbord customization,
-reset the saved login name or rest the saved layout.
-At least four buttons come, started with 'Help', 'Create VM', 'Create CT' and 'Logout'.
+Log Panel
+~~~~~~~~~
-The Body has 3 sections:
+The main purpose of the log panel is to show you what is currently
+going on in your cluster. Actions like creating an new VM are executed
+in the background, and we call such a background job a 'task'.
-* On the left side is the navigation bar. On the top, you can select one of 4
- views. Those views change the structure of the tree below. The default
- selection is *Server View* and it has the following 4 types of elements.
-** Datacenter: contains all the settings belonging to all machines.
-** Nodes: represent the host where the VM/CT runs on. It is named like
- the hostname. Normally the name was set by the installation.
-** Entity: can be a VM, container, a template or a storage.
-** Logical pools: it is possible to group entities to a group for easy management.
-* On the right side is the main management center, where all content
- of the selected entity form the navigation bar is shown.
-* On the bottom is the task log section, where all tasks are shown.
+Any output from such a task is saved into a separate log file. You can
+view that log by simply double-click a task log entry. It is also
+possible to abort a running task there.
-Dataceter Level
----------------
+Please note that we display the most recent tasks from all cluster nodes
+here. So you can see when somebody else is working on another cluster
+node in real-time.
-[thumbnail="gui-datacenter-search.png"]
+NOTE: We remove older and finished task from the log panel to keep
+that list short. But you can still find those tasks within the node panel in the
+'Task History'.
-On the datacenter level you can access cluster wide settings and information.
+Some short-running actions simply send logs to all cluster
+members. You can see those messages in the 'Cluster log' panel.
-* *Search:* it is possible to search anything in cluster
-,this can be a node, VM, Container, Storage or a pool.
-* *Summary:* gives a brief overview over the cluster health.
+Content Panels
+--------------
-* *Options:* can show and set defaults, which apply cluster wide.
+When you select an item from the resource tree, the corresponding
+object displays configuration and status information in the content
+panel. The following sections provide a brief overview of this
+functionality. Please refer to the corresponding chapters in the
+reference documentation to get more detailed information.
-* *Storage:* is the place where a storage will add/managed/removed.
-* *Backup:* has the capability to schedule Backups. This is
- cluster wide, so you do not care about where the VM/Container are on
- your cluster at schedule time.
+Datacenter
+~~~~~~~~~~
-* *Permissions:* will manage user and group permission, LDAP,
- MS-AD and Two-Factor authentication can be setup here.
+[thumbnail="screenshot/gui-datacenter-search.png"]
-* *HA:* will manage the {pve} High-Availability
+On the datacenter level, you can access cluster-wide settings and information.
-* *Firewall:* on this level the Proxmox Firewall works cluster wide and
- makes templates which are cluster wide available.
+* *Search:* perform a cluster-wide search for nodes, VMs, containers, storage
+ devices, and pools.
-* *Support:* here you get all information about your support subscription.
+* *Summary:* gives a brief overview of the cluster's health and resource usage.
-If you like to have more information about this see the corresponding chapter.
+* *Cluster:* provides the functionality and information necessary to create or
+ join a cluster.
+* *Options:* view and manage cluster-wide default settings.
-Node Level
-----------
+* *Storage:* provides an interface for managing cluster storage.
-[thumbnail="gui-node-summary.png"]
+* *Backup:* schedule backup jobs. This operates cluster wide, so it doesn't
+ matter where the VMs/containers are on your cluster when scheduling.
-All belongs of a node can be managed at this level.
+* *Replication:* view and manage replication jobs.
-* *Search:* it is possible to search anything on the node,
- this can be a VM, Container, Storage or a pool.
+* *Permissions:* manage user, group, and API token permissions, and LDAP,
+ MS-AD and Two-Factor authentication.
-* *Summary:* gives a brief overview over the resource usage.
+* *HA:* manage {pve} High Availability.
-* *Shell:* log you in the shell of the node.
+* *ACME:* set up ACME (Let's Encrypt) certificates for server nodes.
-* *System:* is for configuring the network, dns and time, and also shows your syslog.
+* *Firewall:* configure and make templates for the Proxmox Firewall cluster wide.
-* *Updates:* will upgrade the system and informs you about new packets.
+* *Metric Server:* define external metric servers for {pve}.
-* *Firewall:* on this level is only for this node.
+* *Notifications:* configurate notification behavior and targets for {pve}.
-* *Disk:* gives you an brief overview about you physical hard drives and
- how they are used.
+* *Support:* display information about your support subscription.
-* *Ceph:* is only used if you have installed a Ceph sever on you
- host. Then you can manage your Ceph cluster and see the status
+
+Nodes
+~~~~~
+
+[thumbnail="screenshot/gui-node-summary.png"]
+
+Nodes in your cluster can be managed individually at this level.
+
+The top header has useful buttons such as 'Reboot', 'Shutdown', 'Shell',
+'Bulk Actions' and 'Help'.
+'Shell' has the options 'noVNC', 'SPICE' and 'xterm.js'.
+'Bulk Actions' has the options 'Bulk Start', 'Bulk Shutdown' and 'Bulk Migrate'.
+
+* *Search:* search a node for VMs, containers, storage devices, and pools.
+
+* *Summary:* display a brief overview of the node's resource usage.
+
+* *Notes:* write custom comments in xref:markdown_basics[Markdown syntax].
+
+* *Shell:* access to a shell interface for the node.
+
+* *System:* configure network, DNS and time settings, and access the syslog.
+
+* *Updates:* upgrade the system and see the available new packages.
+
+* *Firewall:* manage the Proxmox Firewall for a specific node.
+
+* *Disks:* get an overview of the attached disks, and manage how they are used.
+
+* *Ceph:* is only used if you have installed a Ceph server on your
+ host. In this case, you can manage your Ceph cluster and see the status
of it here.
-* *Task History:* here all past task are shown.
+* *Replication:* view and manage replication jobs.
-* *Subscription:* here you can upload you subscription key and get a
- system overview in case of a support case.
+* *Task History:* see a list of past tasks.
-VM Level
---------
+* *Subscription:* upload a subscription key, and generate a system report for
+ use in support cases.
+
+
+Guests
+~~~~~~
-[thumbnail="gui-qemu-summary.png"]
+[thumbnail="screenshot/gui-qemu-summary.png"]
-There are two differed kinds of VM types and both types can be converted to a template.
-One of them are Kernel-based Virtual Machine (KVM) and the other one are Linux Containers (LXC).
-General the navigation are the same only some option are different.
+There are two different kinds of guests and both can be converted to a template.
+One of them is a Kernel-based Virtual Machine (KVM) and the other is a Linux Container (LXC).
+Navigation for these are mostly the same; only some options are different.
-In the main management center the VM navigation begin if a VM is selected in the left tree.
+To access the various guest management interfaces, select a VM or container from
+the menu on the left.
-The top header contains important VM operation commands like 'Start', 'Shutdown', 'Rest',
-'Remove', 'Migrate', 'Console' and 'Help'.
-Two of them have hidden buttons like 'Shutdown' has 'Stop' and
-'Console' contains the different consolen typs 'SPICE' or 'noVNC'.
+The header contains commands for items such as power management, migration,
+console access and type, cloning, HA, and help.
+Some of these buttons contain drop-down menus, for example, 'Shutdown' also contains
+other power options, and 'Console' contains the different console types:
+'SPICE', 'noVNC' and 'xterm.js'.
-On the right side the content switch white the focus of the option.
+The panel on the right contains an interface for whatever item is selected from
+the menu on the left.
-On the left side.
-All available options are listed one below the other.
+The available interfaces are as follows.
-* *Summary:* gives a brief overview over the VM activity.
+* *Summary:* provides a brief overview of the VM's activity and a `Notes` field
+ for xref:markdown_basics[Markdown syntax] comments.
-* *Console:* an interactive console to your VM.
+* *Console:* access to an interactive console for the VM/container.
-* *(KVM)Hardware:* shows and set the Hardware of the KVM VM.
+* *(KVM)Hardware:* define the hardware available to the KVM VM.
-* *(LXC)Resources:* defines the LXC Hardware opportunities.
+* *(LXC)Resources:* define the system resources available to the LXC.
-* *(LXC)Network:* the LXC Network settings.
+* *(LXC)Network:* configure a container's network settings.
-* *(LXC)DNS:* the LXC DNS settings.
+* *(LXC)DNS:* configure a container's DNS settings.
-* *Options:* all VM options can be set here, this distinguishes between KVM and LXC.
+* *Options:* manage guest options.
-* *Task History:* here all previous task from this VM will be shown.
+* *Task History:* view all previous tasks related to the selected guest.
-* *(KVM) Monitor:* is the interactive communication interface to the KVM process.
+* *(KVM) Monitor:* an interactive communication interface to the KVM process.
-* *Backup:* shows the available backups from this VM and also create a backupset.
+* *Backup:* create and restore system backups.
-* *Snapshots:* manage VM snapshots.
+* *Replication:* view and manage the replication jobs for the selected guest.
-* *Firewall:* manage the firewall on VM level.
+* *Snapshots:* create and restore VM snapshots.
-* *Permissions:* manage the user permission for this VM.
+* *Firewall:* configure the firewall on the VM level.
-Storage Level
--------------
+* *Permissions:* manage permissions for the selected guest.
-[thumbnail="gui-storage-summary-local.png"]
-In this view we have a two partition split view.
+Storage
+~~~~~~~
+
+[thumbnail="screenshot/gui-storage-summary-local.png"]
+
+As with the guest interface, the interface for storage consists of a menu on the
+left for certain storage elements and an interface on the right to manage
+these elements.
+
+In this view we have a two partition split-view.
On the left side we have the storage options
-and on the right side the content of the selected option will shown.
+and on the right side the content of the selected option will be shown.
+
+* *Summary:* shows important information about the storage, such as the type,
+ usage, and content which it stores.
+
+* *Content:* a menu item for each content type which the storage
+ stores, for example, Backups, ISO Images, CT Templates.
-* *Summary:* show you important information about your storage like
-'Usage', 'Type', 'Content', 'Active' and 'Enabled'.
+* *Permissions:* manage permissions for the storage.
-* *Content:* Here all contend will listed grouped by content.
-* *Permissions:* manage the user permission for this storage.
+Pools
+~~~~~
-Logical Pool Level
-------------------
+[thumbnail="screenshot/gui-pool-summary-development.png"]
-[thumbnail="gui-pool-summary-development.png"]
+Again, the pools view comprises two partitions: a menu on the left,
+and the corresponding interfaces for each menu item on the right.
-In this view we have a two partition split view.
-On the left side we have the logical pool options
-and on the right side the content of the selected option will shown.
+* *Summary:* shows a description of the pool.
-* *Summary:* show the description of the pool.
+* *Members:* display and manage pool members (guests and storage).
-* *Members:* Here all members of this pool will listed and can be managed.
+* *Permissions:* manage the permissions for the pool.
-* *Permissions:* manage the user permission for this pool.
+
+Tags
+----
+
+[thumbnail="screenshot/gui-qemu-summary-tags-edit.png", float="left"]
+
+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 is selected.
+
+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. To save or cancel the changes,
+you can use the `✓` and `x` button respectively.
+
+Tags can also be set via the CLI, where multiple tags are separated by semicolons.
+For example:
+
+----
+# qm set ID --tags myfirsttag;mysecondtag
+----
+
+Style Configuration
+~~~~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-datacenter-tag-style.png"]
+
+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
+color to white (#FFFFFF).
+
+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 (see
+xref:pveum_permission_management[Permission Management]). If you want to
+restrict this behavior, appropriate permissions can be set under
+__Datacenter -> Options -> User Tag Access__:
+
+* `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.
+
+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 can be
+edited under __Datacenter -> Options -> Registered Tags__ or via the CLI.
+
+
+For more details on the exact options and how to invoke them in the CLI, see
+xref:datacenter_configuration_file[Datacenter Configuration].
ifdef::wiki[]
endif::wiki[]
-////
-TODO:
-
-VM, CT, Storage, Pool section
-
-////
projects / pve-docs.git / blobdiff