Overview
========

Hostproc is an SNMP agent that makes information from the local
proc(5) filesystem avaialable for remote querying via SNMP.  In other
words, it provides detailed information about processes running on a
host over SNMP.  The information is grouped in a way similar to the
ps(1) output.  Additional aggregating features allow the administrator
to provide summary statistics for processes matching some criteria and
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.

The program is built as a sub-agent for Net-SNMP and is Linux-specific.

Build requirements
==================

GNU make, Net-SNMP libraries and headers.

Installation
============

Run make to build the package and make install (as root) to install
it.  A number of variables (described below) control the compilation
and installation process.  To define these, run

  make config

first, then edit the file config.mk.  When done, run make.

. CFLAGS

  Compilation flags for cc.
  
. CPPFLAGS

  Include paths (-I DIR), and other preprocessor flags.
  
. NET_SNMP_CONFIG

  Name of the net-snmp-config program.  It is needed to determine
  program loader flags and libraries.  Normally it is determined
  automatically. Make will bail out if unable to do so.  In this case,
  you will have to set this variable manually, otherwise just leave it
  as it is.
  
. PREFIX

  Installation prefix.  Unless expressly overridden, all package
  components will be installed under this prefix.  The default value
  is `/usr/local'.

. SBINDIR

  Installation directory for the hostproc binary.  Default is
  $(PREFIX)/sbin.

. DATAROOTDIR

  Root directory for architecture-independent files (MIBs,
  documentation, etc).  Default is $(PREFIX)/share.

. MANDIR

  Installation directory for manual pages.  Default is $(DATAROOTDIR)/man.

. MIBDIR

  Installation directory for HOSTPROC-MIB.txt.  Default is
  $(DATAROOTDIR)/snmp/mibs.

Local testing
=============

To test the package without installing it, you will need three
virtual consoles, each of them with the current working directory in
the hostproc source tree.  The console A will run the snmpd daemon,
the console B the hostproc agent, and the console C will be used to
query the daemon with snmpwalk or snmpget.

Consoles A and B must run with root privileges.

It is assumed that the server where hostproc is installed already runs
the snmpd daemon.  To avoid interfering with it, select a port on
which the test instance of snmpd will be run.  For the purpose of the
following instructions, the port 1161 is selected.

1. In console A, run

     snmpd -c test/snmpd.conf -Le -f udp:localhost:1161
     
2. In console B, run

     ./hostproc -f

3. In console C, run

     snmpwalk -v 1 -c public -M +$(pwd) -Oq localhost:1161 HOSTPROC-MIB::hostprocMIB

You will see the detailed process listing printed on stdout in form of
the HOSTPROC-MIB tree.  Consult the HOSTPROC-MIB.txt file for the
meaning of each OID.

Further reading
===============

Complete documentation is included with the package, both in man
and Texinfo formats. After successful installation, use

   info hostproc

to read the Texinfo documentation.  To read the manpages, use:

   man 8 hostproc

An online copy of the documentation is available
at http://puszcza.gnu.org.ua/software/hostproc.

Bug reporting
=============

Report bugs and suggestions to <gray@gnu.org>.

Copyright
=========

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.

A copy of the GNU General Public License is available in the file
COPYING, distributed with this package.

