libgtop/doc/white-paper.texi

@node White Paper, Reference Manual, About, Top
@chapter LibGTop White Paper

@menu
* Introduction::                Introduction
* Overview::                    Overview
* Servers and Daemons::         Servers and Daemons
@end menu

@node Introduction, Overview, White Paper, White Paper
@section Introduction

Many modern UNIX systems like Solaris, BSD or Digitial Unix only allow
priviledged processes to read information like CPU and Memory Usage or
information about running processes.

@itemize @bullet
@item
BSD, for instance, doesn't have any other way to get those data than reading
directly from @file{/dev/kmem} and you need to be in the @code{kmem} group to
be able to read this.

@item
Other systems, like Digital Unix, allow all users to get things like CPU and
Memory statistics, but only root may read information about any process other
than the current one (you may not even get information about your own processes
if you're not root).

@item
Linux has a very nice @file{/proc} filesystem, but reading and parsing
@file{/proc} is very slow and inefficient.

@item
Solaris is a bit better, but you still need to be in the @code{sys} group or
even root to get some data.
@end itemize

Because of this system utilities like @code{ps}, @code{uptime} or @code{top}
often are setgid kmem or setuid root. Usually, they're also very specific to
the system they're written for and not easily portable to other systems without
a lot of work.

This, of cause, becomes a problem for graphical tools like @code{gtop} - making
a GTK+ program setgid or even setuid would be a security hole as big as you can
drive the entire X11 source code through. For the GNOME project, we also needed
some kind of library which provides all the required information in a portable
since there's more than just one single program that wants to use them - for
instance @code{gtop} and the @code{multiload}, @code{cpumemusage} and
@code{netload} panel applets.

@node Overview, Servers and Daemons, Introduction, White Paper
@section Overview

This section should give you a short overview on how LibGTop was developed, which
things needed to be considered and how it works.

@menu
* Interface Design::            Things that need to be considered
* Server Implementation::       The LibGTop "server"
@end menu

@node Interface Design, Server Implementation, Overview, Overview
@subsection Interface Design

At the very beginning, it was necessary to collect all the data the library part
should provide and put them into some C structures. This was not that easiy as it
might sound since LibGTop should be portable to any modern UNIX system with a common
library part on all those systems, but the data that should be returned vary from
system to system. For instance some systems support shared memory, but some others
may not.

The header files where we define these C structures (which are system-independent) are
shared between client and server. This way we can call the system dependent code
directly where we do not need any special privileges to do so.

All of those structures contain a @code{flags} member which is interpreted as a bit
mask and tells the caller of the library functions which of the fields in the returned
structure are valid and which are not.

@node Server Implementation,  , Interface Design, Overview
@subsection Server Implementation

The LibGTop @dfn{server} is a setgid/setuid binary which contains all the system
dependent code which needs special privileges. It is only build if it's required
on the current system (for instance, the Linux kernel provides all the required
data via its @file{/proc} filesystem so we do not need the server at all) and it
only contains the @dfn{features} which need privileges.

Whenever we do not need any privileges to get all the data for some of the requested
structures (here called @dfn{features}) the library calls the sysdeps code directly
rather than using the server.

@node Servers and Daemons,  , Overview, White Paper
@section Servers and Daemons

LibGTop gives you the possibility to use different LibGTop "servers" and
"daemons" in your application.

Normally you do not need to worry about this things since LibGTop auto-
matically opens a pipe to its server it it's required, but this can also
be customized to fit your needs.

For instance if you have a small applet which is only interested in disk
usage there's no need to fork a separate server process since you don't
need any privileges to get them on any of the supported systems. This can
be archieved with a special call to @code{glibtop_init_r} on startup.

There's also an option to tell @code{glibtop_init_r} that you're only
interested in several features - for instance cpu and memory usage. In
this case LibGTop will only fork a server process if it's required to get
cpu and memory.

You can also tell @code{glibtop_init_r} to start the server only on demand,
this might become useful in command-line based programs. For graphical
applications it's normally best to start the server directly during their
initialization. The same applies for any time critical applications (since
@code{fork} is an expensive operation on some systems this may lead to
incorrect statistics).

LibGTop also allows you to talk to a remote machine using the
@dfn{LibGTop daemon}. This daemon is based on @code{gnuserv} from
GNU Emacs and should be run as an unprivileged user. It has support
for either @code{xauth} or host based authorization.

This daemon itself behaves like a LibGTop client application, i.e. it
forks a server process if this is required.

The main use for this daemon is when you want to monitor a machine which
is either very slow or has very low disk space. In this case you don't need
to install the whole client application (for instance GTop) on the remote
machine but only a very small (maybe also statically linked) executable and
run the graphical application on a more powerful machine.

It can also be used to monitor a remote machine over a very slow link such
as a dialup connection since the conversation between LibGTop client and
daemon uses much less bandwith than an ordinary X11 connection.