Host System Administration
==========================
+include::attributes.txt[]
{pve} is based on the famous https://www.debian.org/[Debian] Linux
distribution. That means that you have access to the whole world of
Debian packages, and the base system is well documented. The
https://debian-handbook.info/download/stable/debian-handbook.pdf[Debian
-Administrator\'s Handbook] is available online, and provide a
+Administrator\'s Handbook] is available online, and provides a
comprehensive introduction to the Debian operating system (see
xref:Hertzog13[]).
* At least two NIC´s, depending on the used storage technology you need more
-Getting Help
-------------
+include::getting-help.adoc[]
-There are basically two different support channels. {pve} itself if
-fully open source, so we always encourage our users to discuss and
-share their knowledge using the http://forum.proxmox.com/[Community
-Support Forum]. The forum is fully moderated by the Proxmox support
-team. Up to now, the forum has about 25.000 members, and more than
-120.000 messages. Needless to say that such a large forum is a great
-place to get information.
+include::pve-package-repos.adoc[]
-The second channel is the commercial support provided by
-{proxmoxGmbh}. {pve} server subscriptions can be ordered online, see
-http://shop.maurer-it.com[{pve} Shop]. For all details see
-http://www.proxmox.com/proxmox-ve/pricing[{pve} Subscription Service
-Plans].
+include::pve-installation.adoc[]
-Please contact the mailto:office@proxmox.com[Proxmox sales team] for
-commercial support requests or volume discounts.
+include::system-software-updates.adoc[]
-Package Repositories
---------------------
-All Debian based systems use
-http://en.wikipedia.org/wiki/Advanced_Packaging_Tool[APT] as package
-management tool. The list of repositories is defined in
-'/etc/apt/sources.list' and '.list' files found inside
-'/etc/apt/sources.d/'. Updates can be installed directly using
-'apt-get', or via the GUI.
+Network Configuration
+---------------------
-Apt 'sources.list' files lists one package repository per line, with
-the most preferred source listed first. Empty lines are ignored, and a
-'#' character anywhere on a line marks the remainder of that line as a
-comment. The information available from the configured sources is
-acquired by 'apt-get update'.
+{pve} uses a bridged networking model. Each host can have up to 4094
+bridges. Bridges are like physical network switches implemented in
+software. All VMs can share a single bridge, as if
+virtual network cables from each guest were all plugged into the same
+switch. But you can also create multiple bridges to separate network
+domains.
+
+For connecting VMs to the outside world, bridges are attached to
+physical network cards. For further flexibility, you can configure
+VLANs (IEEE 802.1q) and network bonding, also known as "link
+aggregation". That way it is possible to build complex and flexible
+virtual networks.
+
+Debian traditionally uses the 'ifup' and 'ifdown' commands to
+configure the network. The file '/etc/network/interfaces' contains the
+whole network setup. Please refer to to manual page ('man interfaces')
+for a complete format description.
+
+NOTE: {pve} does not write changes directly to
+'/etc/network/interfaces'. Instead, we write into a temporary file
+called '/etc/network/interfaces.new', and commit those changes when
+you reboot the node.
+
+It is worth mentioning that you can directly edit the configuration
+file. All {pve} tools tries hard to keep such direct user
+modifications. Using the GUI is still preferable, because it
+protect you from errors.
+
+Naming Conventions
+~~~~~~~~~~~~~~~~~~
-.File '/etc/apt/sources.list'
-----
-deb http://ftp.debian.org/debian jessie main contrib
+We currently use the following naming conventions for device names:
-# security updates
-deb http://security.debian.org jessie/updates main contrib
-----
+* Ethernet devices: eth[N], where 0 ≤ N (`eth0`, `eth1`, ...)
-In addition, {pve} provides three different package repositories.
+* Bridge names: vmbr[N], where 0 ≤ N ≤ 4094 (`vmbr0` - `vmbr4094`)
-{pve} Enterprise Repository
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Bonds: bond[N], where 0 ≤ N (`bond0`, `bond1`, ...)
-This is the default, stable and recommended repository, available for
-all {pve} subscription users. It contains the most stable packages,
-and is suitable for production use. You need a valid subscription key
-to access this repository. The `pve-enterprise` repository is enabled
-by default:
+* VLANs: Simply add the VLAN number to the device name,
+ separated by a period (`eth0.50`, `bond1.30`)
-.File '/etc/apt/sources.list.d/pve-enterprise.list'
-----
-deb https://enterprise.proxmox.com/debian jessie pve-enterprise
-----
+This makes it easier to debug networks problems, because the device
+names implies the device type.
-NOTE: You can disable this repository by commenting out the above line
-using a '#' (at the start of the line). This prevents error messages
-if you do not have a subscription key. Please configure the
-`pve-no-subscription` repository in that case.
+Default Configuration using a Bridge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-As soon as updates are available, the `root@pam` user is notified via
-email about the available new packages. On the GUI, the change-log of
-each package can be viewed (if available), showing all details of the
-update. So you will never miss important security fixes.
+The installation program creates a single bridge named `vmbr0`, which
+is connected to the first ethernet card `eth0`. The corresponding
+configuration in '/etc/network/interfaces' looks like this:
-{pve} No-Subscription Repository
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----
+auto lo
+iface lo inet loopback
+
+iface eth0 inet manual
+
+auto vmbr0
+iface vmbr0 inet static
+ address 192.168.10.2
+ netmask 255.255.255.0
+ gateway 192.168.10.1
+ bridge_ports eth0
+ bridge_stp off
+ bridge_fd 0
+----
-As the name suggests, you do not need a subscription key to access
-this repository. It can be used for testing and non-production
-use. Its not recommended to run on production servers, as these
-packages are not always heavily tested and validated.
+Virtual machines behave as if they were directly connected to the
+physical network. The network, in turn, sees each virtual machine as
+having its own MAC, even though there is only one network cable
+connecting all of these VMs to the network.
-We recommend to configure this repository in '/etc/apt/sources.list'.
-.File '/etc/apt/sources.list'
-----
-deb http://ftp.debian.org/debian jessie main contrib
+Routed Configuration
+~~~~~~~~~~~~~~~~~~~~
-# PVE pve-no-subscription repository provided by proxmox.com,
-# NOT recommended for production use
-deb http://download.proxmox.com/debian jessie pve-no-subscription
+Most hosting providers do not support the above setup. For security
+reasons, they disable networking as soon as they detect multiple MAC
+addresses on a single interface.
-# security updates
-deb http://security.debian.org jessie/updates main contrib
-----
+TIP: Some providers allows you to register additional MACs on there
+management interface. This avoids the problem, but is clumsy to
+configure because you need to register a MAC for each of your VMs.
-
-{pve} Test Repository
-~~~~~~~~~~~~~~~~~~~~~~
+You can avoid the problem by "routing" all traffic via a single
+interface. This makes sure that all network packets use the same MAC
+address.
-Finally, there is a repository called `pvetest`. This one contains the
-latest packages and is heavily used by developers to test new
-features. As usual, you can configure this using
-'/etc/apt/sources.list' by adding the following line:
+A common scenario is that you have a public IP (assume 192.168.10.2
+for this example), and an additional IP block for your VMs
+(10.10.10.1/255.255.255.0). We recommend the following setup for such
+situations:
-.sources.list entry for `pvetest`
----
-deb http://download.proxmox.com/debian jessie pvetest
+auto lo
+iface lo inet loopback
+
+auto eth0
+iface eth0 inet static
+ address 192.168.10.2
+ netmask 255.255.255.0
+ gateway 192.168.10.1
+ post-up echo 1 > /proc/sys/net/ipv4/conf/eth0/proxy_arp
+
+
+auto vmbr0
+iface vmbr0 inet static
+ address 10.10.10.1
+ netmask 255.255.255.0
+ bridge_ports none
+ bridge_stp off
+ bridge_fd 0
----
-Installing {pve}
-----------------
+Masquerading (NAT) with iptables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-{pve} ships as a set of Debian packages, so you can simply install it
-on top of a normal Debian installation. After configuring the
-repositories, you need to run:
+In some cases you may want to use private IPs behind your Proxmox
+host's true IP, and masquerade the traffic using NAT:
-[source,bash]
----
-apt-get update
-apt-get install proxmox-ve
+auto lo
+iface lo inet loopback
+
+auto eth0
+#real IP adress
+iface eth0 inet static
+ address 192.168.10.2
+ netmask 255.255.255.0
+ gateway 192.168.10.1
+
+auto vmbr0
+#private sub network
+iface vmbr0 inet static
+ address 10.10.10.1
+ netmask 255.255.255.0
+ bridge_ports none
+ bridge_stp off
+ bridge_fd 0
+
+ post-up echo 1 > /proc/sys/net/ipv4/ip_forward
+ post-up iptables -t nat -A POSTROUTING -s '10.10.10.0/24' -o eth0 -j MASQUERADE
+ post-down iptables -t nat -D POSTROUTING -s '10.10.10.0/24' -o eth0 -j MASQUERADE
----
-While this looks easy, it presumes that you have correctly installed
-the base system, and you know how you want to configure and use the
-local storage. Network configuration is also completely up to you.
-
-In general, this is not trivial, especially when you use LVM or
-ZFS. This is why we provide an installation CDROM for {pve}. That
-installer just ask you a few questions, then partitions the local
-disk(s), installs all required packages, and configures the system
-including a basic network setup. You can get a fully functional system
-within a few minutes, including the following:
-
-* Complete operating system (Debian Linux, 64-bit)
-* Partition the hard drive with ext4 (alternative ext3 or xfs) or ZFS
-* {pve} Kernel with LXC and KVM support
-* Complete toolset
-* Web based management interface
-
-NOTE: By default, the complete server is used and all existing data is
-removed.
-
-Further configuration is done via the Proxmox web interface. Just
-point your browser to the IP address given during installation
-(https://youripaddress:8006). Proxmox VE is tested for IE9, Firefox 10
-and higher, Google Chrome (latest).
-
-
-Network Configuration
----------------------
-
-Basic network setup.
-
-image::images/cluster-nwdiag.svg[{pve} Cluster Network]
+////
+TODO: explain IPv6 support?
+TODO: explan OVS
+////
-image::images/node-nwdiag.svg[{pve} Default Network Setup]
+////
+TODO:
Local Storage
-------------
TODO: explain persistent journal...
+////
projects / pve-docs.git / blobdiff