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

[pve-docs.git] / pve-gui.adoc

[[chapter_gui]]
Graphical User Interface
========================
ifndef::manvolnum[]
:pve-toplevel:
endif::manvolnum[]

{pve} is simple. There is no need to install a separate management
tool, and everything can be done through your web browser (Latest
Firefox or Google Chrome is preferred). A built-in HTML5 console is
used to access the guest console. As an alternative,
https://www.spice-space.org/[SPICE] can be used.

Because we use the Proxmox cluster file system (pmxcfs), you can
connect to any node to manage the entire cluster. Each node can manage
the entire cluster. There is no need for a dedicated manager node.

You can use the web-based administration interface with any modern
browser. When {pve} detects that you are connecting from a mobile
device, you are redirected to a simpler, touch-based user interface.

The web interface can be reached via https://youripaddress:8006
(default login is: 'root', and the password is specified during the
installation process).


Features
--------

* Seamless integration and management of {pve} clusters

* AJAX technologies for dynamic updates of resources

* Secure access to all Virtual Machines and Containers via SSL
  encryption (https)

* Fast search-driven interface, capable of handling hundreds and
  probably thousands of VMs

* Secure HTML5 console or SPICE

* Role based permission management for all objects (VMs, storages,
  nodes, etc.)

* Support for multiple authentication sources (e.g. local, MS ADS,
  LDAP, ...)

* Two-Factor Authentication (OATH, Yubikey)

* 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="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.

To the right of the search bar we see the identity (login name). The
gear symbol is a button opening the 'My Settings' dialog. There you
can customize some client side user interface setting (reset the saved
login name, reset saved layout).

The rightmost part of the header contains four buttons:

[horizontal]
Help :: Opens a new browser window showing the reference documentation.

Create VM :: Opens the virtual machine creation wizard.

Create CT :: Open the container creation wizard.

Logout :: Logout, and show the login dialog again.


[[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.

Storage View:: Only shows storage objects, grouped by nodes.

Pool View:: Show VMs and containers, grouped by pool.


Log Panel
~~~~~~~~~

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'.

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.

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.

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'.

Some short-running actions simply send logs to all cluster
members. You can see those messages in the 'Cluster log' panel.


Content Panels
--------------

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.


Datacenter
~~~~~~~~~~

[thumbnail="screenshot/gui-datacenter-search.png"]

On the datacenter level, you can access cluster-wide settings and information.

* *Search:* perform a cluster-wide search for nodes, VMs, containers, storage
   devices, and pools.

* *Summary:* gives a brief overview of the cluster's health and resource usage.

* *Cluster:* provides the functionality and information necessary to create or
   join a cluster.

* *Options:* view and manage cluster-wide default settings.

* *Storage:* provides an interface for managing cluster storage.

* *Backup:* schedule backup jobs. This operates cluster wide, so it doesn't
   matter where the VMs/containers are on your cluster when scheduling.

* *Replication:* view and manage replication jobs.

* *Permissions:* manage user, group, and API token permissions, and LDAP,
   MS-AD and Two-Factor authentication.

* *HA:* manage {pve} High Availability.

* *ACME:* set up ACME (Let's Encrypt) certificates for server nodes.

* *Firewall:* configure and make templates for the Proxmox Firewall cluster wide.

* *Metric Server:* define external metric servers for {pve}.

* *Support:* display information about your support subscription.


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.

* *Replication:* view and manage replication jobs.

* *Task History:* see a list of past tasks.

* *Subscription:* upload a subscription key, and generate a system report for
   use in support cases.


Guests
~~~~~~

[thumbnail="screenshot/gui-qemu-summary.png"]

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.

To access the various guest management interfaces, select a VM or container from
the menu on the left.

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'.

The panel on the right contains an interface for whatever item is selected from
the menu on the left.

The available interfaces are as follows.

* *Summary:* provides a brief overview of the VM's activity and a `Notes` field
  for xref:markdown_basics[Markdown syntax] comments.

* *Console:* access to an interactive console for the VM/container.

* *(KVM)Hardware:* define the hardware available to the KVM VM.

* *(LXC)Resources:* define the system resources available to the LXC.

* *(LXC)Network:* configure a container's network settings.

* *(LXC)DNS:* configure a container's DNS settings.

* *Options:* manage guest options.

* *Task History:* view all previous tasks related to the selected guest.

* *(KVM) Monitor:* an interactive communication interface to the KVM process.

* *Backup:* create and restore system backups.

* *Replication:* view and manage the replication jobs for the selected guest.

* *Snapshots:* create and restore VM snapshots.

* *Firewall:* configure the firewall on the VM level.

* *Permissions:* manage permissions for the selected guest.


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 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.

* *Permissions:* manage permissions for the storage.


Pools
~~~~~

[thumbnail="screenshot/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.

* *Summary:* shows a description of the pool.

* *Members:* display and manage pool members (guests and storage).

* *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
--------

* link:/wiki/Central_Web-based_Management

endif::wiki[]