Merge lp:~ahasenack/landscape-client/sysinfo-manpage-303274 into lp:~landscape/landscape-client/trunk

[Andreas Hasenack]

This branch adds a manpage for landscape-sysinfo(1), originally written by Jonathan Marsden (https://launchpad.net/~jmarsden) and further changed by myself. It also changes the way the debian packaging installs the manpages by using a file called debian/<package>.manpages and listing the manpages inside it.

[Jamu Kakar (jkakar)]

[1]

I was expecting a man/landscape-sysinfo.txt file, which would be the
source for a manpage generated by txt2man...?

[2]

+in that configuration file, under the section \fI[sysinfo]\fP, by replacing the hifen

s/hifen/hyphen/ please.

[3]

Nice work on the manpage contents!

review: Needs Information

[Andreas Hasenack (ahasenack)]

[1]
I didn't create one, since I got the manpage from the bug ticket by a contributor. Do we need the .txt files or are they there just to create the manpage? If they just serve as a template for the manpage, I vote to delete them. I recall we had issues with txt2man in different distributions not working as we wanted and that being a blocker once upon a time for us to update the manpages.

[2]
fixed

[3]
er, fixed :)

[lp:~ahasenack/landscape-client/sysinfo-manpage-303274]

314. By Andreas Hasenack on 2011-01-20

hyphen spelling

[Jamu Kakar (jkakar)]

Andreas:

I find the text files much easier to read and edit. Also, to answer
your question, they are just source files for txt2man to generate
manpages. Even though we had some problems, it seems like we don't
have them now, and it'd be nice to keep the writing/editing process
simple.

[Andreas Hasenack (ahasenack)]

I tried txt2man in all distros. It generated broken manpages on dapper and hardy, basically escaping a control char that it shouldn't:
"\\fB--version\fP" should have been "\fB--version\fP", for example. As a result, the manpage looks like:

"""
(...)
OPTIONS
       \fB--version
              Show program’s version number and exit.

       \fB-h, --help
              Show this help message and exit.
(...)
"""

Unmerged revisions

314. By Andreas Hasenack on 2011-01-20

hyphen spelling

313. By Andreas Hasenack on 2011-01-20

Use package.manpages to install the manpages, and include the new sysinfo
manpage in the list.

312. By Andreas Hasenack on 2011-01-20

- use package name in header, without a version though
- correct markup for filenames

311. By Andreas Hasenack on 2011-01-20

A whole bunch of updates to the manpage.

310. By Andreas Hasenack on 2011-01-20

Added first draft of a manpage for landscape-sysinfo from Jonathan Marsden
(https://launchpad.net/~jmarsden).

=== added file 'debian/landscape-client.manpages'
--- debian/landscape-client.manpages	1970-01-01 00:00:00 +0000
+++ debian/landscape-client.manpages	2011-01-20 18:53:28 +0000
@@ -0,0 +1,3 @@
+man/landscape-client.1
+man/landscape-config.1
+man/landscape-message.1
 
=== added file 'debian/landscape-common.manpages'
--- debian/landscape-common.manpages	1970-01-01 00:00:00 +0000
+++ debian/landscape-common.manpages	2011-01-20 18:53:28 +0000
@@ -0,0 +1,1 @@
+man/landscape-sysinfo.1
 
=== modified file 'debian/rules'
--- debian/rules	2011-01-11 23:04:59 +0000
+++ debian/rules	2011-01-20 18:53:28 +0000
@@ -70,7 +70,7 @@
 	dh_testdir
 	dh_testroot
 	dh_installdocs
-	dh_installman -p landscape-client man/landscape-client.1 man/landscape-config.1 man/landscape-message.1
+	dh_installman
 	dh_installchangelogs
 	dh_install --sourcedir debian/tmp/
 	dh_installinit -- start 45 2 3 4 5 . stop 15 1 .
 
=== added file 'man/landscape-sysinfo.1'
--- man/landscape-sysinfo.1	1970-01-01 00:00:00 +0000
+++ man/landscape-sysinfo.1	2011-01-20 18:53:28 +0000
@@ -0,0 +1,134 @@
+.TH LANDSCAPE-SYSINFO "1" "14 January 2011" "landscape-common" "User Commands"
+.SH NAME
+landscape-sysinfo \- display a summary of the current system status
+.SH SYNOPSIS
+.B landscape-sysinfo
+[\fIoptions\fR]
+.SH DESCRIPTION
+.B landscape-sysinfo
+is a utility that displays information about the computer it is run
+on. This information is displayed upon login for console users
+(ssh and terminal login supported) and can also be seen at anytime
+by just calling \fBlandscape-sysinfo\fP from the command line.
+
+The information displayed at login time is updated by \fBupdate-motd\fP. On
+systems where \fBupdate-motd\fP is not available, such as Ubuntu Dapper or
+Hardy, the output of \fBlandscape-sysinfo\fP is not included.
+
+The output of \fBlandscape-sysinfo\fP can be controlled by enabling or
+disabling its plugins. See below how to do that.
+
+If the system load is higher than the number of cores, as determined by the
+count of \fIprocessor\fP lines in \fI/proc/cpuinfo\fP, then
+\fBlandscape-sysinfo\fP will not run at login time. This is to prevent it from
+potentially making a bad situation worse by interfering with what could be an
+administrator logging in to try to fix the problem causing the high load.
+
+.SH OPTIONS
+.TP
+\fB\-\-version\fR
+show landscape-sysinfo's version number and exit
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+show this help message and exit
+.TP
+\fB\-c\fR FILE, \fB\-\-config\fR=\fIFILE\fR
+Use config from this file (any command line options
+override settings from the file) (default:
+\fI/etc/landscape/client.conf\fP).
+.TP
+\fB\-d\fR PATH, \fB\-\-data\-path\fR=\fIPATH\fR
+The directory to store data files in (default:
+\fI/var/lib/landscape/client/\fP).
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Do not log to the standard output.
+.TP
+\fB\-l\fR FILE, \fB\-\-log\-dir\fR=\fIFILE\fR
+The directory to write log files to (default:
+\fI/var/log/landscape\fP).
+.TP
+\fB\-\-log\-level\fR=\fILOG_LEVEL\fR
+One of debug, info, warning, error or critical.
+.TP
+\fB\-\-ignore\-sigint\fR
+Ignore interrupt signals.
+.TP
+\fB\-\-ignore\-sigusr1\fR
+Ignore SIGUSR1 signal to rotate logs.
+.TP
+\fB\-\-sysinfo\-plugins\fR=\fIPLUGIN_LIST\fR
+Comma\-delimited list of sysinfo plugins to use.
+Default is to use all plugins.
+.TP
+\fB\-\-exclude\-sysinfo\-plugins\fR=\fIPLUGIN_LIST\fR
+Comma\-delimited list of sysinfo plugins to NOT use.
+This always take precedence over plugins to include.
+.PP
+Default plugins: Load, Disk, Memory, Temperature, Processes, LoggedInUsers,
+LandscapeLink, Network
+.SH CONFIGURATION FILE
+The configuration file controlling the behaviour of \fBlandscape-sysinfo\fP is
+\fI/etc/landscape/client.conf\fP and it is shared with the
+\fBlandscape-client\fP program.
+
+Any of the long command-line options can be used as a configuration directive
+in that configuration file, under the section \fI[sysinfo]\fP, by replacing the hyphen
+(-) with an underscore (_).
+
+For example, to disable the \fILandscapeLink\fP and \fITemperature\fP plugins
+without having to use the command line option, the following can be added to
+\fI/etc/landscape/client.conf\fP:
+.PP
+.nf
+.fam C
+    [sysinfo]
+    exclude_sysinfo_plugins = Temperature, LandscapeLink
+.fam T
+.fi    
+
+.SH EXAMPLES
+This is the default configuration, with all plugins enabled:
+.PP
+.nf
+.fam C
+    $ landscape-sysinfo
+      System load:    0.66               Processes:             242
+      Usage of /home: 72.0% of 27.50GB   Users logged in:       1
+      Memory usage:   31%                IP address for wlan0:  10.0.1.6
+      Swap usage:     0%                 IP address for virbr0: 192.168.122.1
+      Temperature:    47 C
+
+      => There is 1 zombie process.
+
+      Graph this data and manage this system at https://landscape.canonical.com/
+.fam T
+.fi
+.TP
+If you want to disable the temperature and Landscape plugins, you could run it like this:
+.PP
+.nf
+.fam C
+    $ landscape-sysinfo --exclude-sysinfo-plugins=Temperature,LandscapeLink
+      System load:    1.08               Processes:             242
+      Usage of /home: 72.0% of 27.50GB   Users logged in:       1
+      Memory usage:   31%                IP address for wlan0:  10.0.1.6
+      Swap usage:     0%                 IP address for virbr0: 192.168.122.1
+
+      => There is 1 zombie process.
+.fam T
+.fi
+
+.SH FILES
+.TP
+.I /etc/landscape/client.conf
+Configuration file
+.TP
+.I /var/log/landscape/sysinfo.log
+Log file for when the tool is run as root. This file will usually be empty,
+unless something wrong happened. In that case, it will have more information
+about the problem.
+When a regular non-root user runs the tool, the log file is \fI~/.landscape/sysinfo.log\fP.
+.SH SEE ALSO
+\fBlandscape-client\fP(1),
+\fBupdate-motd\fP(5)