proxmox/README.md

# proxmox

#### Table of Contents

1. [Overview](#overview)
2. [Module Description](#module-description)
3. [Setup](#setup)
    * [What Proxmox affects](#what-proxmox-affects)
    * [Beginning with Proxmox](#beginning-with-proxmox)
4. [Usage](#usage)
    * [Hypervisor](#hypervisor)
    * [VM](#vm)
5. [Reference](#reference)
    * [Classes](#classes)
    * [Defined types](#defined-types)
    * [Parameters](#parameters)
6. [Other notes](#other-notes)
7. [Limitations](#limitations)
8. [Development](#development)
9. [License](#license)

## Overview

The proxmox module provide a simple way to manage Proxmox hypervisor and OpenVZ network's configuration with Puppet.

## Module Description

The proxmox module automates installing Proxmox on Debian systems.

## Setup

### What Proxmox affects:

* Package/service/configuration files for Proxmox
* A new `sources.list` file for Proxmox
* System repository
* The static table lookup for hostnames `hosts`
* Users and group permissions for WebGUI.
* WebGUI's service (pveproxy)
* Kernel modules loaded at the boot time.
* OpenVZ's configuration file.
* OpenVZ's service.
* OpenVZ CT network's configuration.

### Beginning with Proxmox

To begin using proxmox module with default parameters, declare the hypervisor's class with `include proxmox::hypervisor`.

## Usage

### Hypervisor

```
include proxmox::hypervisor
```
**Note**: The module will automatically reboot the system on the PVE Kernel. You will need to start again the puppet agent.

#### KVM only

If you will use only KVM you can have a most recent kernel with:
```
class { 'proxmox::hypervisor':
  kvm_only => true,
}
```

#### Disable additionnal modules
Disable all additionnal modules load at the boot time:
```
class { 'proxmox::hypervisor':
  pve_modules_list => [ '' ],
}
```

### VM

Only OpenVZ is supported right now but the vm's class will check-it by it self:
```
include proxmox::vm
```

#### proxmox::vm::openvz

Automatically call by the `proxmox::vm` class, it will manage network configuration, but only few configurations are possible:
* Only one Virtual Ethernet device (aka veth) and it will work with **DHCP**.
* If a veth is available, it will be the main network's interface (set the default gateway throught eth0).
* If a veth is available, only one Virtual Network device (aka venet) as chance to work (the first one), because all others routes will be flushed.
* If there are only venet: no changes.

## Reference

### Classes

* `proxmox`: Main class, do nothing right now.

* `proxmox::hypervisor`: Install the Proxmox hypervisor on the system.

* `proxmox::vm`: Manage virtual machines and containers.

### Defined types

* `proxmox::hypervisor::group`: Manage groups for Proxmox WebGUI and set permissions.

```
proxmox::hypervisor::group { 'sysadmin':
  role  => "Administrator",
  users => [ 'user1@pam', 'toto@pve' ],
}
```

* `proxmox::hypervisor::user`: Manage user for Proxmox WebGUI.

```
proxmox::hypervisor::user { 'marvin':
  group => 'sysadmin',
}
```

  Mainly used by the `proxmox::hypervisor::group` defined type to create the group, permissions and also create/add the users to a group. Because to add a user to a group via this defined type, the group should already exist.

### Parameters

#### proxmox::hypervisor

* `ve_pkg_ensure`: What to set the Virtual Environnment package to. Can be 'present', 'absent' or 'version'. Defaults to 'present'.
* `ve_pkg_name`: The list of VirtualEnvironnment packages. Can be an array [ 'proxmox-ve-2.6.32', 'ksm-control-daemon', 'vzprocps', 'open-iscsi', 'bootlogd', 'pve-firmware' ].
* `kvm_only`: If set to 'true', Puppet will install a newer kernel compatible only with KVM. Accepts 'true' or 'false'. Defaults to 'false'.
* `kernel_kvm_pkg_name`: The list of packages to install the newer kernel. Can be an array [ 'pve-kernel-3.10.0-5-pve', '...' ].
* `kernel_pkg_name`: The list of packages to install a kernel compatible with both KVM and OpenVZ. Can be an array [ 'pve-kernel-2.6.32-34-pve', '...' ].
* `rec_pkg_name`: The list of recommended and usefull packages for Proxmox. Can be an array [ 'ntp', 'ssh', 'lvm2', 'bridge-utils' ].
* `old_pkg_ensure`: What to set useless packages (non recommended, previous kernel, ...). Can be 'present' or 'absent'. Defaults to 'absent'.
* `old_pkg_name`: The list of useless packages. Can be an array [ 'acpid',  'linux-image-amd64', 'linux-base', 'linux-image-3.2.0-4-amd64' ].
* `pve_enterprise_repo_ensure`: Choose to keep the PVE enterprise repository. Can be 'present' or 'absent'. Defaults to 'absent'.
* `pveproxy_default_path`: Path of the configuration file read by the PveProxy service. Defaults to '/etc/default/pveproxy'.
* `pveproxy_default_content`: Template file use to generate the previous configuration file. Default to 'proxmox/hypervisor/pveproxy_default.erb'.
* `pveproxy_allow`:   Can be ip addresses, range or network; separated by a comma (example: '192.168.0.0/24,10.10.0.1-10.10.0.5'). Defaults to '127.0.0.1'.
* `pveproxy_deny`: Unauthorized IP addresses. Can be 'all' or ip addresses, range or network; separated by a comma. Defaults to 'all'.
* `pveproxy_policy`: The policy access. Can be 'allow' or 'deny'. Defaults to 'deny'.
* `pveproxy_service_name`: WebGUI's service name (replace Apache2 since v3.0). Defaults to 'pveproxy'.
* `pveproxy_service_manage`: If set to 'true', Puppet will manage the WebGUI's service. Can be 'true' or 'false'. Defaults to 'true'.
* `pveproxy_service_enabled`: If set to 'true', Puppet will ensure the WebGUI's service is running. Can be 'true' or 'false'. Defaults to 'true'.
* `pve_modules_list`: The list of additionnal modules to load at boot time.
* `pve_modules_file_path`: The configuration file that will contain the modules list. Defaults to '/etc/modules-load.d/proxmox.conf'.
* `pve_modules_file_content`: Template file used to generate the previous configuration file. Defaults to 'proxmox/hypervisor/proxmox_modules.conf.erb'.
* `vz_config_file_path`: Path of the main OpenVZ's configuration file. Defaults to '/etc/vz/vz.conf'.
* `vz_config_file_tpl`: Template file use to generate the OpenVZ's configuration file. Defaults to 'proxmox/hypervisor/vz.conf.erb'.
* `vz_iptables_modules`: If set to 'true', OpenVZ will share a list of iptables modules to the containers. Can be 'true' or 'false'. Defaults to 'true'.
* `vz_service_name`: The OpenVZ's service name. Defaults to 'vz'.
* `vz_service_manage`: If set to 'true', Puppet will manage the OpenVZ's service. Can be 'true' or 'false'. Defaults to 'true'.
* `vz_service_enabled`: If set to 'true', Puppet will ensure the OpenVZ's service is running. Can be 'true' or 'false'. Defaults to 'true'.
* `labs_firewall_rule`: If set to 'true', Puppet will set a iptable rule to allow WebGUI and VNC's port access. Can be 'true' or 'false'. Defaults to 'false'.

#### proxmox::vm
* `vm_interfaces_path`: The main network configuration's file. Defaults to '/etc/network/interfaces'.
* `vm_interfaces_content`: Template file used to generate the previous configuration file. Defaults to 'proxmox/vm/openvz_interfaces.erb'.
* `vm_interfaces_tail_path`: A second network configuration file that will be concatenated in the main. Defaults to '/etc/network/interfaces.tail'.
* `vm_interfaces_tail_content`: Template file used to generate the previous configuration file. Defaults to 'proxmox/vm/openzv_interfaces.tail.erb'.
* `network_service_name`: Network's service name. Defaults to 'networking'.
* `network_service_manage`: If set to 'true', Puppet will manage the network's service. Can be 'true' or 'false'. Defaults to 'true'.
* `network_service_enabled`: If set to 'true', Puppet will ensure the network's service is running. Can be 'true' or 'false'. Defaults to 'true'.

Other notes
-----------
By default `proxmox::hypervisor` comes with several modules kernel load at boot time. Mainly iptables's modules to allow it in the OpenVZ CT.

The default modules list:
* `iptable_filter`
* `iptable_mangle`
* `iptable_nat`
* `ipt_length` (=xt_length)
* `ipt_limit` (=xt_limit)
* `ipt_LOG`
* `ipt_MASQUERADE`
* `ipt_multiport` (=xt_multiport)
* `ipt_owner` (=xt_owner)
* `ipt_recent` (=xt_recent)
* `ipt_REDIRECT`
* `ipt_REJECT`
* `ipt_state` (=xt_state)
* `ipt_TCPMSS` (=xt_TCPMSS)
* `ipt_tcpmss` (=xt_tcpmss)
* `ipt_TOS`
* `ipt_tos`
* `ip_conntrack` (=nf_conntrack)
* `ip_nat_ftp` (=nf_nat_ftp)
* `xt_iprange`
* `xt_comment`
* `ip6table_filter`
* `ip6table_mangle`
* `ip6t_REJECT' `

See [hypervisor usage](#hypervisor) if you want to disable it or [parameters](#parameters) if you want to edit this list.

Limitations
-----------

This module will only work on Debian 7.x versions.

Development
-----------

Free to send contributions, fork it, ...

License
-------

WTFPL (http://wtfpl.org/)