[pve-devel] [PATCH docs 2/3] add pveperf section and man page

[Fabian Grünbichler]

this is a bit ugly, because pveperf is not an instance of
PVE::CLIHandler, and we can't use the regular API generator.
the actual installed man page is still generated via the pod
data contained in pve-manager/bin/pveperf ...
---
 Makefile                     |  4 +++-
 pve-admin-guide.adoc         | 10 +++++++++
 pve-doc-generator.mk         |  8 ++++++++
 pve-system-requirements.adoc | 10 +++++++++
 pveperf.1-synopsis.adoc      |  1 +
 pveperf.adoc                 | 48 ++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 80 insertions(+), 1 deletion(-)
 create mode 100644 pveperf.1-synopsis.adoc
 create mode 100644 pveperf.adoc

diff --git a/Makefile b/Makefile
index cf166fe..61c249f 100644
--- a/Makefile
+++ b/Makefile
@@ -54,7 +54,8 @@ COMMAND_LIST=		\
 	pvesm 		\
 	pveum 		\
 	vzdump 		\
-	ha-manager
+	ha-manager	\
+	pveperf
 
 SERVICE_LIST=		\
 	pve-firewall 	\
@@ -150,6 +151,7 @@ PVE_ADMIN_GUIDE_SOURCES=			\
 	${PVEAM_MAN1_SOURCES}			\
 	${PVESUBSCRIPTION_MAN1_SOURCES}		\
 	${PVECEPH_MAN1_SOURCES}			\
+	${PVEPERF_MAN1_SOURCES}			\
 	pve-bibliography.adoc			\
 	$(addsuffix .adoc, ${COMMAND_LIST}) 	\
 	$(addsuffix .adoc, ${SERVICE_LIST}) 	\
diff --git a/pve-admin-guide.adoc b/pve-admin-guide.adoc
index 93b204c..63a9d3c 100644
--- a/pve-admin-guide.adoc
+++ b/pve-admin-guide.adoc
@@ -67,6 +67,8 @@ include::pveceph.adoc[]
 
 include::pvesubscription.adoc[]
 
+include::pveperf.adoc[]
+
 
 :leveloffset: 1
 
@@ -96,6 +98,14 @@ include::pvesubscription.1-synopsis.adoc[]
 
 :leveloffset: 0
 
+*pveperf* - {pve} Benchmark Script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:leveloffset: 1
+include::pveperf.1-synopsis.adoc[]
+
+:leveloffset: 0
+
 *pveceph* - Manage CEPH Services on {pve} Nodes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/pve-doc-generator.mk b/pve-doc-generator.mk
index 0f97202..1d68b4a 100644
--- a/pve-doc-generator.mk
+++ b/pve-doc-generator.mk
@@ -139,6 +139,11 @@ PMXCFS_MAN8_SOURCES=			\
 	pmxcfs.8-cli.adoc		\
 	${PVE_COMMON_DOC_SOURCES}
 
+PVEPERF_MAN1_SOURCES=			\
+	pveperf.adoc			\
+	pveperf.1-synopsis.adoc		\
+	${PVE_COMMON_DOC_SOURCES}
+
 attributes.txt docinfo.xml:
 	cp ${DGDIR}/$@ $@.tmp
 	mv $@.tmp $@
@@ -151,6 +156,9 @@ attributes.txt docinfo.xml:
 	${DGDIR}/gen-$*-adoc.pl >$@.tmp
 	mv $@.tmp $@
 
+pveperf.1-synopsis.adoc:
+	echo '*pveperf* `[PATH]`' > pveperf.1-synopsis.adoc
+
 %.1-synopsis.adoc:
 	perl -I. -e "use PVE::CLI::$(subst -,_,$*);print PVE::CLI::$(subst -,_,$*)->generate_asciidoc_synopsys();" > $@.tmp
 	mv $@.tmp $@
diff --git a/pve-system-requirements.adoc b/pve-system-requirements.adoc
index 64a4ac5..19ddd2c 100644
--- a/pve-system-requirements.adoc
+++ b/pve-system-requirements.adoc
@@ -42,6 +42,16 @@ Recommended System Requirements
 
 * At least two NICs, depending on the used storage technology you need more
 
+
+Simple Performance Overview
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On an installed {pve} system, you can run the included `pveperf` script
+to obtain an overview of the CPU and hard disk performance.
+
+NOTE: this is just a very quick and general benchmark. More detailed tests
+are recommended, especially regarding the I/O performance of your system.
+
 Supported web browsers for accessing the web interface
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 To use the web interface you need a modern browser, this includes:
diff --git a/pveperf.1-synopsis.adoc b/pveperf.1-synopsis.adoc
new file mode 100644
index 0000000..7a163e2
--- /dev/null
+++ b/pveperf.1-synopsis.adoc
@@ -0,0 +1 @@
+*pveperf* `[PATH]`
diff --git a/pveperf.adoc b/pveperf.adoc
new file mode 100644
index 0000000..b0f7322
--- /dev/null
+++ b/pveperf.adoc
@@ -0,0 +1,48 @@
+ifdef::manvolnum[]
+PVE({manvolnum})
+================
+include::attributes.txt[]
+
+NAME
+----
+
+pveperf - the Proxmox benchmark
+
+
+SYNOPSIS
+--------
+
+include::pveperf.1-synopsis.adoc[]
+
+DESCRIPTION
+-----------
+endif::manvolnum[]
+
+ifndef::manvolnum[]
+pveperf - Proxmox VE Benchmark Script
+=====================================
+include::attributes.txt[]
+endif::manvolnum[]
+
+Tries to gather some CPU/hard disk performance data on the hard disk
+mounted at `PATH` (`/` is used as default):
+
+CPU BOGOMIPS:: bogomips sum of all CPUs
+
+REGEX/SECOND:: regular expressions per second (perl performance test), should
+be above 300000
+
+HD SIZE:: hard disk size
+
+BUFFERED READS:: simple HD read test. Modern HDs should reach at least 40
+MB/sec
+
+AVERAGE SEEK TIME:: tests average seek time. Fast SCSI HDs reach values < 8
+milliseconds. Common IDE/SATA disks get values from 15 to 20 ms.
+
+FSYNCS/SECOND:: value should be greater than 200 (you should enable `write
+back` cache mode on you RAID controller - needs a battery backed cache (BBWC)).
+
+DNS EXT:: average time to resolve an external DNS name
+
+DNS INT:: average time to resolve a local DNS name
-- 
2.1.4