diff options
| -rw-r--r-- | Makefile | 2 | ||||
| -rw-r--r-- | doc/download.texi | 4 | ||||
| -rw-r--r-- | doc/hostproc.8 | 347 | ||||
| -rw-r--r-- | doc/hostproc.texi | 2 | ||||
| -rw-r--r-- | proctab.c | 2 | ||||
| -rw-r--r-- | table.c | 2 |
6 files changed, 6 insertions, 353 deletions
@@ -241,7 +241,7 @@ MAKEINFOHTML = $(MAKEINFO) --html webdoc: $(MAKEINFO) -I $(docdir) --html \ - -c EXTRA_HEAD='<link rel="stylesheet" type="text/css" href="css/info.css"/><link rel="stylesheet" type="text/css" href="css/hostproc.css"/><script src="js/modernizr.js" type="text/javascript"></script><script src="js/info.js" type="text/javascript"></script>' doc/hostproc.texi -o $(docdir)/webdoc + -c EXTRA_HEAD='<link rel="stylesheet" type="text/css" href="/css/info.css"/><link rel="stylesheet" type="text/css" href="/css/project.css"/><script src="/js/modernizr.js" type="text/javascript"></script><script src="/js/info.js" type="text/javascript"></script>' doc/hostproc.texi -o $(docdir)/webdoc # ####################### diff --git a/doc/download.texi b/doc/download.texi index ae5e74d..dfe723d 100644 --- a/doc/download.texi +++ b/doc/download.texi @@ -4,8 +4,8 @@ The latest version of the package is: @*@b{File}: @uref{https://download.gnu.org.ua/release/hostproc/hostproc-@value{VERSION}.tar.gz, hostproc-@value{VERSION}.tar.gz}. @*@b{Size}: 193K -@*@b{MD5}: -@*@b{SHA1}: +@*@b{MD5}: c50fe9704730ab17246b868bb1993f34 +@*@b{SHA1}: 5413458b55dca32aa46c002cb4412c1926e43b1e This and earlier releases of @samp{hostproc} are available for download from @uref{https://download.gnu.org.ua/release/hostproc/}. diff --git a/doc/hostproc.8 b/doc/hostproc.8 deleted file mode 100644 index 462c40b..0000000 --- a/doc/hostproc.8 +++ /dev/null @@ -1,347 +0,0 @@ -.\" This file is part of hostproc -.\" Copyright (C) 2020 Sergey Poznyakoff -.\" -.\" Hostproc is free software; you can redistribute it and/or modify it -.\" under the terms of the GNU General Public License as published by the -.\" Free Software Foundation; either version 3 of the License, or (at your -.\" option) any later version. -.\" -.\" Hostproc is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public License along -.\" with hostproc. If not, see <http://www.gnu.org/licenses/>. */ -.TH HOSTPROC 8 "October 28, 2022" "HOSTPROC" "System Manager's Manual" -.SH NAME -hostproc \- process list SNMP agent -.SH SYNOPSIS -.nh -.na -\fBhostproc\fR\ - [\fB\-?ACHdfh\fR]\ - [\fB\-D\fR \fITOKEN\fR[\fB,\fITOKEN\fR...]]\ - [\fB\-L\fR[\fBeEfFoOsS\fR]]\ - [\fB\-c\fR \fIFILE\fR]\ - [\fB\-p\fR \fIFILE\fR] -.ad -.hy -.SH DESCRIPTION -Hostproc provides detailed information about processes running on a -host over SNMP. The information is grouped in a way similar to the -.BR ps (1) -output. Additional aggregating features allow the administrator -to provide summary statistics for processes matching some criteria or -to exclude such processes from the detailed output. The latter feature -can be used, in particular, to separate statistics for processes running -on the host from those that are run within docker containers. -.PP -The program is an AgentX agent for -.BR snmpd (8). -To enable agentx, add the following statement to the -.B snmpd.conf -file: -.sp -.nh -.na - master agentx -.ad -.hy -.PP -Upon startup, the program searches for its configuration file -\fBhostproc.conf\fR in the Net-SNMP configuration path, reads it, -detaches itself from the controlling terminal and continues running in -background. -.PP -It logs its messages via the \fBsyslog\fR facility \fBdaemon\fR. -.PP -Command line options can be used to alter this behavior. In -particular, the \fB\-f\fR option instructs the program to remain in -foreground and to log its diagnostics on the standard error. -.SH MIB -Please see the file \fBHOSTPROC-MIB.txt\fR for the description of OID -instances returned by \fBhostproc\fR. In general, they fall into the -following five categories: management variables, process table, -process group table, exclusion group table and system memory -information. -.SS Management variables -These supply information about the running instance of -\fBhostproc\fR and provide facilities for its remote management. -.PP -The \fBhostprocUpTime\fR variable holds the number of seconds expired -since the program was started. -.PP -The \fBprocessGroupModify\fR variable, when set to a correctly -formatted JSON request, applies the requested modifications to a -process group (see below). This allows the administrator to create, -delete or modify groups remotely. It is used, in particular, by the -.BR stevedore (8) -SNMP agent to reflect the information about running docker services in -the exclusion group table. -.SS Process table -The \fBprocessTable\fR subtree contains information about running -processes. Each conceptual row represents a single process. It -contains the following information: PID, parent PID, UID, GID, average -and instantaneous CPU usage (percent), CPU time used in this process, -process state, nice and priority values, virtual and resident set -sizes, process name (argv[0]), process command line, and process -executable file name. -.PP -The table is indexed by the process ID (PID). -.SS Process groups -The entries in the \fBprocessGroupTable\fR aggregate information about -processes with names matching a certain pattern, defined in the -configuration file. Here, "name" can be the process argv[0] name, -the executable name, or the full command line. Either exact or -regular expression matching can be used. -.PP -The group definition in the configuration file can impose limits on -one or more of the following parameters: minimum and maximum number of -processes in the group, virtual memory, RSS or CPU it uses. If the -aggregated data don't fall within given limits, the \fBprocessGroupOK\fR -instance is reset to \fBfalse\fR to indicate a problem with that group. -.PP -The information included in each processGroupTable entry is: process -matching criteria (the field of the processTable entry used for -selection and the type of matching implemented), the process OK status, -the actual number of processes in this group, the total amount of -virtual memory and RSS they occupy, average, instantaneous and maximum -CPU usage, as well as the limits configured for these values. -.SS processExcludedTable -This table hosts exclusion process groups. An exclusion group -aggregates processes that descend from a common set of ancestor -processes. These ancestor processes are selected by their name, as -was described for \fBprocessGroupTable\fR. The descendants of these -processes are excluded from both the \fBprocessTable\fR and -\fBprocessGroupTable\fR, and their summary statistics is collected in -the exclusion group. -.PP -Each entry in this table describes a single exclusion group and has -the same structure as the \fBprocessGroupTable\fR. In particular, the -same set of limits can be imposed on the processes in this group. -.SS System memory information -The \fBhostMemInfo\fR subtree contains information about available and -free amount of RAM and swap. -.SH OPTIONS -.TP -.B \-A -When logging to a file (\fB\-Lf\fR), append to it, rather than -truncating it. -.TP -.B \-C -Do not read default configuration files. Useful together with the -\fB\-c\fR option. -.TP -\fB\-D\fR \fITOKEN\fR[\fB,\fITOKEN\fR...] -Turn on debugging for the given \fITOKEN\fRs. The \fB\-DALL\fR -enables maximum debugging output. Note, that this option works only -if Net-SNMP has been configured with debugging enabled. Otherwise, it -is a no-op. -.TP -.B \-H -Display a list of configuration file directives understood by the -agent and then exit. -.TP -\fB\-L\fR[\fBeEfFoOsS\fR] -Configure logging. See the section -.B LOGGING OPTIONS -in -.BR snmpcmd (1) -for details. -.TP -\fB\-c\fR \fIFILE\fR -Read \fIFILE\fR as a configuration file (or a comma-separated list of -configuration files) -.TP -.B -d -Dump (in hexadecimal) the sent and received SNMP packets. -.TP -.B -f -Remain in foreground. -.TP -\fB\-p\fR \fIFILE\fR -Write PID to \fIFILE\fR. This overrides the \fBpidfile\fR -configuration statement. -.TP -\fB\-h\fR, \fB\-?\fR -Print a short usage summary. -.SH CONFIGURATION -The configuration file \fBhostproc.conf\fR is searched in the default -configuration path (inspect the output of \fBhostproc \-h\fR to obtain -its value). The first file found is read and parsed. You can also -specify the full name of the configuration file using the \fB\-c\fR -command line option. -.PP -The file syntax is similar to the syntax of \fBsnmpd.conf\fR: each -statement consists of the keyword and value, separated by any amount -of whitespace. -.PP -The following statements are understood: -.TP -\fBpsinterval\fR \fIN\fR -Specifies how often the \fB/proc\fR filesystem is rescanned. The -argument \fIN\fR is the interval in seconds. The default is 30. -.TP -\fBpidfile\fR \fISTR\fR -Declares the name of the PID file. When started, hostproc will -create this file and write its PID value to it. Before exiting, -it will remove the file. -.TP -\fBgroup\fR \fINAME\fR -Create a process group \fINAME\fR. This statement should be followed -by one or more of the following substatements, which configure details -of that group: -.BR pattern , -.BR field , -.BR match , -.BR min , -.BR max , -.BR vsize , -.BR rss , -.BR cpu . -These are described in detail below. If none of them is supplied, the -group will contain processes whose command name (argv[0]) is -\fINAME\fR, with no particular limits on their count, memory or CPU usage. -.TP -\fBpattern\fR \fISTRING\fR -Defines the pattern that the name of a process must match in order -for that process to be included in the group. Defaults to the \fINAME\fR -argument to the \fBgroup\fR statement. -.TP -\fBfield\fR \fBcomm\fR | \fBexe\fR | \fBcmdline\fR -Specifies what to match against the pattern: \fBcomm\fR (the default) -means argv[0], \fBexe\fR means full pathname of the executable file and -\fBcmdline\fR means entire command line. -.sp -\fBNote:\fR To be able to use the \fBexe\fR setting, \fBhostproc\fR -must run with the superuser (root) privileges. -.TP -\fBmatch\fR \fBexact\fR | \fBbasename\fR | \fBrx\fR | \fBregex\fR -Specifies how to match the selected field against the pattern: -\fBexact\fR (the default) means exact byte-to-byte comparison, -\fBbasename\fR means to compare only base names of pattern and string, -and \fBrx\fR pr \fBregex\fR means that pattern is an extended regular -expression. -.TP -\fBmin\fR \fINUM\fR -Sets the minimum allowed number of running processes in the group. -.TP -\fBmax\fR \fINUM\fR -Sets the maximum allowed number of running processes in the group. -.TP -\fBvsize\fR \fISIZE\fR -Sets the maximum total usage of virtual memory for the group. -\fISIZE\fR is a number, optionally followed by \fBk\fR (\fBK\fR), for -kilobytes, \fBm\fR (\fBM\fR) for megabytes, or \fBg\fR (\fBG\fR), for -gigabytes. In the absence of any suffix, kilobytes are assumed. -.TP -\fBrss\fR \fISIZE\fR -Sets the maximum total resident set size, in kilobytes. The size -suffixes described above (for \fBvsize\fR) are also allowed. -.TP -\fBcpu\fR \fIPCT\fR -Sets the maximum CPU usage for the group (percent). -.TP -\fBproc\fR \fINAME\fR [\fIMAX\fR] [\fIMIN\fR] -This is a shortcut for the \fBgroup\fR declaration, compatible with -the same statement in -.BR snmpd.conf (5). -.sp -It creates a process group \fINAME\fR. The group will include processes -with the process name (\fBargv[0]\fR) \fINAME\fR. The \fIMAX\fR and -\fIMIN\fR parameters define maximum and minimum allowed number of -running processes for that group. If the number of processes in the -group becomes less than \fIMIN\fR or greater than \fIMAX\fR, then the -corresponding \fBprocessGroupOK\fR instance will be set to false (1). -.sp -If neither \fIMAX\fR nor \fIMIN\fR are specified, they will default to -infinity and 1 respectively ("at least one"). If only \fIMAX\fR is -specified, \fIMIN\fR will default to 0 ("no more than \fIMAX\fR"). If -\fIMAX\fR is 0 and \fIMIN\fR is not, this indicates infinity ("at -least \fIMIN\fR"). If both \fIMAX\fR and \fIMIN\fR are 0, this -indicates a process that should not be running. -.sp -The \fBproc\fR statement is equivalent to -.sp -.nh -.na -group \fINAME\fR - pattern \fINAME\fR - field comm - match exact - min \fIMIN\fR - max \fIMAX\fR -.ad -.hy -.TP -\fBexclude\fR \fINAME\fR -Create exclusion group \fINAME\fR. The exclusion group is similar to the -process group described above, except that the \fIfield\fR, -\fIpattern\fR, and \fImatch\fR keywords select ancestors of the group -members, not the members themselves. -.sp -The \fBexclude\fR declaration can be followed by one or more -statements valid for the \fBgroup\fR statement. In the absence of -any of these, it is equivalent to: -.sp -.nh -.na -exclude \fINAME\fR - pattern \fINAME\fR - field comm - match exact -.ad -.hy -.SH NOTE -This manpage is a short description of \fBhostproc\fR. For a detailed -discussion, including examples and usage recommendations, refer to the -\fBHostproc Manual\fR available in texinfo format. If the \fBinfo\fR -reader and the \fBhostproc\fR documentation are properly installed on your -system, the command -.PP -.RS +4 -.B info hostproc -.RE -.PP -should give you access to the complete manual. -.PP -You can also view the manual using the info mode in -.BR emacs (1), -or find it in various formats online at -.PP -.RS +4 -.B http://puszcza.gnu.org.ua/software/hostproc -.RE -.PP -If any discrepancies occur between this manpage and the -\fBHostproc Manual\fR, the later shall be considered the authoritative -source. -.SH "SEE ALSO" -The MIB in \fBHOSTPROC-MIB.txt\fR. -.sp -.BR snmpd (8), -.BR snmpd.conf (5), -.BR snmpcmd (1), -.BR stevedore (8). -.SH AUTHORS -Sergey Poznyakoff -.SH "BUG REPORTS" -Report bugs to <gray@gnu.org>. -.SH COPYRIGHT -Copyright \(co 2022 Sergey Poznyakoff -.br -.na -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -.ad -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. -.\" Local variables: -.\" eval: (add-hook 'write-file-functions 'time-stamp) -.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \"" -.\" time-stamp-format: "%:B %:d, %:y" -.\" time-stamp-end: "\"" -.\" time-stamp-line-limit: 20 -.\" end: - diff --git a/doc/hostproc.texi b/doc/hostproc.texi index b9fa868..cf03e2e 100644 --- a/doc/hostproc.texi +++ b/doc/hostproc.texi @@ -27,7 +27,7 @@ @end ifinfo @copying -Copyright @copyright{} 2022 Sergey Poznyakoff +Copyright @copyright{} 2020--2022 Sergey Poznyakoff Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -1,5 +1,5 @@ /* hostproc - SNMP agent for monitoring detailed list of running processes - Copyright (C) 2020 Sergey Poznyakoff + Copyright (C) 2020-2022 Sergey Poznyakoff Hostproc is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the @@ -1,5 +1,5 @@ /* hostproc - SNMP agent for monitoring detailed list of running processes - Copyright (C) 2020 Sergey Poznyakoff + Copyright (C) 2020-2022 Sergey Poznyakoff Hostproc is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the |