sysadmin.adoc: split into several smaller files
authorDietmar Maurer <dietmar@proxmox.com>
Tue, 19 Jan 2016 16:03:26 +0000 (17:03 +0100)
committerDietmar Maurer <dietmar@proxmox.com>
Tue, 19 Jan 2016 16:03:26 +0000 (17:03 +0100)
Makefile
getting-help.adoc [new file with mode: 0644]
pve-installation.adoc [new file with mode: 0644]
pve-package-repos.adoc [new file with mode: 0644]
sysadmin.adoc
system-software-updates.adoc [new file with mode: 0644]

index 90110a8..5ae615a 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -7,8 +7,15 @@ PVEFW_SOURCES=attributes.txt pve-firewall.adoc pve-firewall.8-synopsis.adoc
 QM_SOURCES=attributes.txt qm.adoc qm.1-synopsis.adoc
 PCT_SOURCES=attributes.txt pct.adoc pct.1-synopsis.adoc
 
+SYSADMIN_SOURCES=                      \
+       getting-help.adoc               \
+       pve-package-repos.adoc          \
+       pve-installation.adoc           \
+       system-software-updates.adoc    \
+       sysadmin.adoc
+
 PVE_ADMIN_GUIDE_SOURCES=               \
-       sysadmin.adoc                   \
+       ${SYSADMIN_SOURCES}             \
        pve-admin-guide.adoc            \
        pve-intro.adoc                  \
        pmxcfs.adoc                     \
diff --git a/getting-help.adoc b/getting-help.adoc
new file mode 100644 (file)
index 0000000..305325a
--- /dev/null
@@ -0,0 +1,19 @@
+Getting Help
+------------
+
+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.
+
+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].
+
+Please contact the mailto:office@proxmox.com[Proxmox sales team] for
+commercial support requests or volume discounts.
diff --git a/pve-installation.adoc b/pve-installation.adoc
new file mode 100644 (file)
index 0000000..ed4e73e
--- /dev/null
@@ -0,0 +1,145 @@
+Installing {pve}
+----------------
+
+{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:
+
+[source,bash]
+----
+apt-get update
+apt-get install proxmox-ve
+----
+
+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 CD-ROM 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.
+
+Using the {pve} Installation CD-ROM
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please insert the installation CD-ROM, then boot from that
+drive. Immediately afterwards you can choose the following menu
+options:
+
+Install Proxmox VE::
+
+Start normal installation.
+
+Install Proxmox VE (Debug mode)::
+
+Start installation in debug mode. It opens a shell console at several
+installation steps, so that you can debug things if something goes
+wrong. Please press `CTRL-D` to exit those debug consoles and continue
+installation. This option is mostly for developers and not meant for
+general use.
+
+Rescue Boot::
+
+This option allows you to boot an existing installation. It searches
+all attached hard disks, and if it finds an existing installation,
+boots directly into that disk using the existing Linux kernel. This
+can be useful if there are problems with the boot block (grub), or the
+BIOS is unable to read the boot block from the disk.
+
+Test Memory::
+
+Runs 'memtest86+'. This is useful to check if your memory if
+functional and error free.
+
+You normally select *Install Proxmox VE* to start the installation.
+After that you get prompted to select the target hard disk(s). The
+`Options` button aside lets you select the target file system, and
+defaults to `ext4`. The installer uses LVM if you select 'ext3',
+'ext4' or 'xfs' as file system, and offers additional option to
+restrict LVM space (see <<advanced_lvm_options,below>>)
+
+If you have more than one disk, you can also use ZFS as file system.
+ZFS supports several software RAID levels, so this is specially useful
+if you do not have a hardware RAID controller. The `Options` button
+lets you select the ZFS RAID level, and you can choose disks there.
+
+The next pages just asks for basic configuration options like time
+zone and keyboard layout. You also need to specify your email address
+and select a superuser password.
+
+The last step is the network configuration. Please note that you can
+use either IPv4 or IPv6 here, but not both. If you want to configure a
+dual stack node, you can easily do that after installation.
+
+If you press `Next` now, installation starts to format disks, and
+copies packages to the target. Please wait until that is finished,
+then reboot the server.
+
+Further configuration is done via the Proxmox web interface. Just
+point your browser to the IP address given during installation
+(https://youripaddress:8006). {pve} is tested for IE9, Firefox 10
+and higher, and Google Chrome.
+
+
+[[advanced_lvm_options]]
+Advanced LVM configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The installer creates a Volume Group (VG) called `pve`, and additional
+Logical Volumes (LVs) called `root`, `data` and `swap`. The size of
+those volumes can be controlled with:
+
+`hdsize`::
+
+Defines the total HD size to be used. This way you can save free
+space on the HD for further partitioning (i.e. for an additional PV
+and VG on the same hard disk that can be used for LVM storage).
+
+`swapsize`::
+
+To define the size of the `swap` volume. Default is the same size as
+installed RAM, with 4GB minimum and `hdsize/8` as maximum.
+
+`maxroot`::
+
+The `root` volume size. The `root` volume stores the whole operation
+system.
+
+`maxvz`::
+
+Define the size of the `data` volume, which is mounted at
+'/var/lib/vz'.
+
+`minfree`::
+
+To define the amount of free space left in LVM volume group `pve`.
+16GB is the default if storage available > 128GB, `hdsize/8` otherwise.
++
+NOTE: LVM requires free space in the VG for snapshot creation (not
+required for lvmthin snapshots).
+
+
+ZFS Performance Tips
+^^^^^^^^^^^^^^^^^^^^
+
+ZFS uses a lot of memory, so it is best to add additional 8-16GB RAM
+if you want to use ZFS.
+
+ZFS also provides the feature to use a fast SSD drive as write cache. The
+write cache is called the ZFS Intent Log (ZIL). You can add that after
+installation using the following command:
+
+ zpool add <pool-name> log </dev/path_to_fast_ssd>
+
diff --git a/pve-package-repos.adoc b/pve-package-repos.adoc
new file mode 100644 (file)
index 0000000..cff1a9f
--- /dev/null
@@ -0,0 +1,86 @@
+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.
+
+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'.
+
+.File '/etc/apt/sources.list'
+----
+deb http://ftp.debian.org/debian jessie main contrib
+
+# security updates
+deb http://security.debian.org jessie/updates main contrib
+----
+
+In addition, {pve} provides three different package repositories.
+
+{pve} Enterprise Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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:
+
+.File '/etc/apt/sources.list.d/pve-enterprise.list'
+----
+deb https://enterprise.proxmox.com/debian jessie pve-enterprise
+----
+
+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.
+
+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.
+
+{pve} No-Subscription Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+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
+
+# PVE pve-no-subscription repository provided by proxmox.com,
+# NOT recommended for production use
+deb http://download.proxmox.com/debian jessie pve-no-subscription
+
+# security updates
+deb http://security.debian.org jessie/updates main contrib
+----
+
+{pve} Test Repository
+~~~~~~~~~~~~~~~~~~~~~~
+
+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:
+
+.sources.list entry for `pvetest`
+----
+deb http://download.proxmox.com/debian jessie pvetest
+----
+
index b439104..6ac4662 100644 (file)
@@ -64,280 +64,13 @@ Recommended system requirements
 * At least two NICĀ“s, depending on the used storage technology you need more
 
 
-Getting Help
-------------
-
-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.
-
-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].
-
-Please contact the mailto:office@proxmox.com[Proxmox sales team] for
-commercial support requests or volume discounts.
-
-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.
-
-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'.
-
-.File '/etc/apt/sources.list'
-----
-deb http://ftp.debian.org/debian jessie main contrib
-
-# security updates
-deb http://security.debian.org jessie/updates main contrib
-----
-
-In addition, {pve} provides three different package repositories.
-
-{pve} Enterprise Repository
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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:
-
-.File '/etc/apt/sources.list.d/pve-enterprise.list'
-----
-deb https://enterprise.proxmox.com/debian jessie pve-enterprise
-----
-
-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.
-
-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.
-
-{pve} No-Subscription Repository
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-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
-
-# PVE pve-no-subscription repository provided by proxmox.com,
-# NOT recommended for production use
-deb http://download.proxmox.com/debian jessie pve-no-subscription
-
-# security updates
-deb http://security.debian.org jessie/updates main contrib
-----
-
-{pve} Test Repository
-~~~~~~~~~~~~~~~~~~~~~~
-
-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:
-
-.sources.list entry for `pvetest`
-----
-deb http://download.proxmox.com/debian jessie pvetest
-----
-
-
-Installing {pve}
-----------------
+include::getting-help.adoc[]
 
-{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:
+include::pve-package-repos.adoc[]
 
-[source,bash]
-----
-apt-get update
-apt-get install proxmox-ve
-----
+include::pve-installation.adoc[]
 
-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 CD-ROM 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.
-
-Using the {pve} Installation CD-ROM
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Please insert the installation CD-ROM, then boot from that
-drive. Immediately afterwards you can choose the following menu
-options:
-
-Install Proxmox VE::
-
-Start normal installation.
-
-Install Proxmox VE (Debug mode)::
-
-Start installation in debug mode. It opens a shell console at several
-installation steps, so that you can debug things if something goes
-wrong. Please press `CTRL-D` to exit those debug consoles and continue
-installation. This option is mostly for developers and not meant for
-general use.
-
-Rescue Boot::
-
-This option allows you to boot an existing installation. It searches
-all attached hard disks, and if it finds an existing installation,
-boots directly into that disk using the existing Linux kernel. This
-can be useful if there are problems with the boot block (grub), or the
-BIOS is unable to read the boot block from the disk.
-
-Test Memory::
-
-Runs 'memtest86+'. This is useful to check if your memory if
-functional and error free.
-
-You normally select *Install Proxmox VE* to start the installation.
-After that you get prompted to select the target hard disk(s). The
-`Options` button aside lets you select the target file system, and
-defaults to `ext4`. The installer uses LVM if you select 'ext3',
-'ext4' or 'xfs' as file system, and offers additional option to
-restrict LVM space (see <<advanced_lvm_options,below>>)
-
-If you have more than one disk, you can also use ZFS as file system.
-ZFS supports several software RAID levels, so this is specially useful
-if you do not have a hardware RAID controller. The `Options` button
-lets you select the ZFS RAID level, and you can choose disks there.
-
-The next pages just asks for basic configuration options like time
-zone and keyboard layout. You also need to specify your email address
-and select a superuser password.
-
-The last step is the network configuration. Please note that you can
-use either IPv4 or IPv6 here, but not both. If you want to configure a
-dual stack node, you can easily do that after installation.
-
-If you press `Next` now, installation starts to format disks, and
-copies packages to the target. Please wait until that is finished,
-then reboot the server.
-
-Further configuration is done via the Proxmox web interface. Just
-point your browser to the IP address given during installation
-(https://youripaddress:8006). {pve} is tested for IE9, Firefox 10
-and higher, and Google Chrome.
-
-
-[[advanced_lvm_options]]
-Advanced LVM configuration options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The installer creates a Volume Group (VG) called `pve`, and additional
-Logical Volumes (LVs) called `root`, `data` and `swap`. The size of
-those volumes can be controlled with:
-
-`hdsize`::
-
-Defines the total HD size to be used. This way you can save free
-space on the HD for further partitioning (i.e. for an additional PV
-and VG on the same hard disk that can be used for LVM storage).
-
-`swapsize`::
-
-To define the size of the `swap` volume. Default is the same size as
-installed RAM, with 4GB minimum and `hdsize/8` as maximum.
-
-`maxroot`::
-
-The `root` volume size. The `root` volume stores the whole operation
-system.
-
-`maxvz`::
-
-Define the size of the `data` volume, which is mounted at
-'/var/lib/vz'.
-
-`minfree`::
-
-To define the amount of free space left in LVM volume group `pve`.
-16GB is the default if storage available > 128GB, `hdsize/8` otherwise.
-+
-NOTE: LVM requires free space in the VG for snapshot creation (not
-required for lvmthin snapshots).
-
-
-ZFS Performance Tips
-^^^^^^^^^^^^^^^^^^^^
-
-ZFS uses a lot of memory, so it is best to add additional 8-16GB RAM
-if you want to use ZFS.
-
-ZFS also provides the feature to use a fast SSD drive as write cache. The
-write cache is called the ZFS Intent Log (ZIL). You can add that after
-installation using the following command:
-
- zpool add <pool-name> log </dev/path_to_fast_ssd>
-
-
-System Software Updates
------------------------
-
-We provide regular package updates on all repositories. You can
-install those update using the GUI, or you can directly run the CLI
-command 'apt-get':
-
- apt-get update
- apt-get dist-upgrade
-
-NOTE: The 'apt' package management system is extremely flexible and
-provides countless of feature - see `man apt-get` or <<Hertzog13>> for
-additional information.
-
-You should do such updates at regular intervals, or when we release
-versions with security related fixes. Major system upgrades are
-announced at the https://forum.proxmox.com/[Forum]. Those announcement
-also contain detailed upgrade instructions.
-
-TIP: We recommend to run regular upgrades, because it is important to
-get the latest security updates.
+include::system-software-updates.adoc[]
 
 
 Network Configuration
diff --git a/system-software-updates.adoc b/system-software-updates.adoc
new file mode 100644 (file)
index 0000000..b1047dd
--- /dev/null
@@ -0,0 +1,21 @@
+System Software Updates
+-----------------------
+
+We provide regular package updates on all repositories. You can
+install those update using the GUI, or you can directly run the CLI
+command 'apt-get':
+
+ apt-get update
+ apt-get dist-upgrade
+
+NOTE: The 'apt' package management system is extremely flexible and
+provides countless of feature - see `man apt-get` or <<Hertzog13>> for
+additional information.
+
+You should do such updates at regular intervals, or when we release
+versions with security related fixes. Major system upgrades are
+announced at the https://forum.proxmox.com/[Forum]. Those announcement
+also contain detailed upgrade instructions.
+
+TIP: We recommend to run regular upgrades, because it is important to
+get the latest security updates.