Skip to content

Commit

Permalink
content transfer between man page and README file
Browse files Browse the repository at this point in the history 
A unique README file is more suitable as a central documentation point,
especially in preparation for multiple executables scenarios.
  • Loading branch information
@guillomovitch
guillomovitch committed Jul 9, 2012
1 parent 6359bd1 commit 7f96303
Show file tree
Hide file tree
Showing 2 changed files with 115 additions and 140 deletions.
136 changes: 110 additions & 26 deletions README
View file
@@ -1,11 +1,13 @@
FusionInventory Agent
FusionInventory agent
---------------------

Description
-----------
The FusionInventory agent is a generic management agent. It can perform a
certain number of tasks, according to its own execution plan, or on behalf of a
GLPI server with fusioninventory plugin, acting as a control point.
The FusionInventory agent is a generic multi-platform agent. It can perform a
large array of management tasks, such as local inventory, software deployment
or network discovery. It can be used either standalone, or in combination
with a compatible server (OCS, GLPI, OTRS) acting as a centralized control
point.

Two of these tasks are included in agent source distribution, local inventory
and wake on lan. Other tasks are distributed separatly, excepted for binary
Expand Down Expand Up @@ -45,6 +47,36 @@ inventory:
- ipssend
- mfiutil

System-specific informations
----------------------------

Supported systems:
- Windows (since Windows 2000)
- GNU/Linux
- MacOSX
- Solaris
- FreeBSD
- NetBSD
- OpenBSD
- AIX
- HP-UX
- GNU/kFreeBSD

On Solaris/SPARC, you must install sneep and record the Serial Number with it.
Download it from http://www.sun.com/download/products.xml?id=4304155a.

On Windows, we use an additional dmidecode binary shipped in the windows
distribution to retrieve many informations not available otherwise, including
fine-grained multi-cores CPUs identification. Unfortunatly, this binary is not
reliable enough to be used on Windows 2003, leading to less precise
inventories.

On any system, the privilege level used to run the agent will change inventory
results. Generally speaking, this means less results when run with lesser
privileges. On Windows, tough, running agent with SYSTEM privileges, which is
implicit if running as a service, does sometimes gives less results, especially
for shared printers only visible from a user account.

Usage
-----
They are two different ways to run the agent:
Expand All @@ -55,14 +87,13 @@ They are two different ways to run the agent:
In the first case, the agent execution scheduling is controlled from local
system, and the memory footprint between agent executions is zero.

In second case, the agent execution scheduling is controlled from GLPI server,
as the agent runs regulary according to a parameter initially set in its
configuration (delaytime), overrided by the server at the first connection
(PROLOG_FREQ). Additionaly, the server may also initiate additional
out-of-schedule executions by sending HTTP requests if the web interface is
used. However, it also mean you have a full perl interpreter loaded in memory
constantly, and a network port open on your system with a process running with
full system privileges attached to it.
In second case, the agent execution scheduling is remotelly controlled,
as the agent runs regulary according to a parameter given by the server at the
first connection (PROLOG_FREQ). Additionaly, the server may also initiate
additional out-of-schedule executions by sending HTTP requests if the web
interface is used. However, it also implies a full perl interpreter loaded in
memory constantly, and a process running with full system privileges listening
on the network.

If you don't need to control agent execution from the server, and if you're
able to periodically launch the agent without resorting to its internal
Expand All @@ -79,22 +110,75 @@ server, a local directory, etc...). Only the local inventory task is compatible
with all kind of targets, tough, all others require a GLPI server target, and
will get discarded for other kind of target.

System-specific informations
----------------------------
On Solaris/SPARC, you must install sneep and record the Serial Number with it.
Download it from http://www.sun.com/download/products.xml?id=4304155a.
Configuration
-------------

On Windows, we use an additional dmidecode binary shipped in the windows
distribution to retrieve many informations not available otherwise, including
fine-grained multi-cores CPUs identification. Unfortunatly, this binary is not
reliable enough to be used on Windows 2003, leading to less precise
inventories.
The agent is able to use multiple configuration backends. The registry backend
is the default on Windows platform, and the file backend is the default
everywhere else. Another backend can be specified using the --config command
line option.

On any system, the privilege level used to run the agent will change inventory
results. Generally speaking, this means less results when run with lesser
privileges. On Windows, tough, running agent with SYSTEM privileges, which is
implicit if running as a service, does sometimes gives less results, especially
for shared printers only visible from a user account.
The file backend reads configuration directives from a configuration file,
whose default location is determined at installation time as
<installation prefix>/etc/agent.cfg. An alternative location can also be given
with --conf-file command-line option.

The registry backend reads configuration directives from the Windows
registry, with an arch-dependant location:
- HKEY_LOCAL_MACHINE\SOFTWARE\FusionInventory-Agent for 32 bits machines
- HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\FusionInventory-Agent for 64 bits machines

The none backend doesn't read any configuration directive at all, allowing
to isolate the agent execution from any installed configuration.

Examples
--------

Execute all available tasks required by a local server:
% fusioninventory-agent --server localhost

Execute all available tasks required by a local server, using a specific
URI:
% fusioninventory-agent --server http://localhost/ocsinventory2

Execute all available tasks required by a local server, using a secure
connection:
% fusioninventory-agent --server https://localhost/ocsinventory

Execute all available tasks required by a local server, using HTTP
authentication:
% fusioninventory-agent --server localhost --user test --password s3cr3t

Execute all available tasks and write the result in /tmp directory:
% fusioninventory-agent --local /tmp

Execute all available tasks and write the result in /tmp directory in
HTML format:
% fusioninventory-agent --local /tmp --html

Server scheduling
-----------------

The FusionInventory agent communicates with its control server using the OCS
Inventory protocol, which is based on XML exchanges over HTTP(s).

Prologue

The agent sends a first message with its identity (DEVICEID). The server
replies with a list of tasks to execute immediatly, a list of parameters, and
the maximum delay before next contact time, as PROLOG_FREQ parameter.

Execution

The agent runs every available tasks requested by the server during the
prologue, and sends the results back to it.

Sleep

The agent then sleeps during a random delay bounded by PROLOG_FREQ parameter
given by the server in the prologue. The exact moment occurs between half of
the value and the full value. For instance, if PROLOG_FREQ value is 3600, the
next contact will occurs between half an hour and an hour.

Security
--------
Expand Down
119 changes: 5 additions & 114 deletions fusioninventory-agent
View file
Expand Up @@ -174,97 +174,13 @@ B<fusioninventory-agent> [options] [--server server|--local path]
--debug debug mode (false)
--version print the version and exit
=head1 EXAMPLES
% fusioninventory-agent --server localhost
# execute all available tasks required by a local server
% fusioninventory-agent --server http://localhost/ocsinventory2
# execute all available tasks required by a local server, using a specific
# URI
% fusioninventory-agent --server https://localhost/ocsinventory
# execute all available tasks required by a local server, using a secure
# connection
% fusioninventory-agent --server localhost --user test --password s3cr3t
# execute all available tasks required by a local server, using HTTP
# authentication
% fusioninventory-agent --local /tmp
# execute all available tasks and write the result in /tmp directory
% fusioninventory-agent --local /tmp --html
# execute all available tasks and write the result in /tmp directory in
# HTML format
=head1 DESCRIPTION
F<fusioninventory-agent> is an agent for OCS Inventory server and
FusionInventory for GLPI servers. It creates local inventory of the machines
(hardware and software) and send it to the server. It can also write it
in a local XML file.
This agent is the successor of the former linux_agent which was released with
OCS 1.01 and prior. It also replaces the Solaris/AIX/BSD unofficial agents.
Supported systems:
=over 4
=item F<Windows> (since Windows 2000)
=item F<GNU/Linux>
=item F<MacOSX>
=item F<Solaris>
=item F<FreeBSD>
=item F<NetBSD>
=item F<OpenBSD>
=item F<AIX>
=item F<HP-UX>
=item F<GNU/kFreeBSD>
=back
=head1 OCS INVENTORY PROTOCOL
FusionInventory Agent uses OCS Inventory protocol and is compatible with OCS
Inventory server. The agent uses the same protocol with the FusionInventory
For GLPI plugin.
The OCS protocol is basicly an exchange of XML file done over HTTP(S).
=head2 First, The PROLOG
The agent send a first message to give it's ID (DEVICEID). The
server send back to the agent an XML file with a list of parameter. It's the
PROLOG RESP. You can see it if you're in Debug mode.
In this PROLOG, the server send the PROLOG_FREQ. The agent will use it to
know when it need to contact the server for the next time.
The agent compute the next query date this way:
PROLOG_FREQ/2+RANDOM(PROLOG_FREQ/2)
=head2 Module execution
The agent will launch each modules and pass the list of options found in the
PROLOG RESP as parameter. The module can send information directly to the
server (inventory, SNMP scan result, etc)
=head2 Server mode (Windows service or Unix daemon)
In server mode, the agent wait during a period between the last PROLOG and
PROLOG_FREQ. If PROLOG_FREQ is not set, it will use --delaytime value.
The default value is 3600.
The F<fusioninventory-agent> agent is a generic multi-platform agent. It can
perform a large array of management tasks, such as local inventory, software
deployment or network discovery. It can be used either standalone, or in
combination with a compatible server (OCS, GLPI, OTRS) acting as a centralized
control point.
=head1 OPTIONS
Expand Down Expand Up @@ -567,28 +483,3 @@ Print the agent setup directories and exit.
Print the version and exit.
=back
=head1 CONFIGURATION
The agent is able to use multiple configuration backends. The registry backend
is the default on Windows platform, and the file backend is the default
everywhere else. Another backend can be specified using the B<--config> option.
The I<file> backend reads configuration directives from a configuration file,
whose default location is determined at installation time as
PREFIX/etc/agent.cfg. An alternative location can also be given with
B<--conf-file> option.
The I<registry> backend reads configuration directives from the Windows
registry, with an arch-dependant location:
=over
=item * F<HKEY_LOCAL_MACHINE\SOFTWARE\FusionInventory-Agent> for 32 bits machines
=item * F<HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\FusionInventory-Agent> for 64 bits machines
=back
The I<none> backend doesn't read any configuration directive at all, allowing
to isolate the agent execution from any installed configuration.

0 comments on commit 7f96303

Please sign in to comment.