OldDocumentation:Agent

From OCS Inventory NG
Jump to: navigation, search

There are 2 methods to inventory a client computer using OCS Inventory NG agent:

  • Direct to server: The agent sends inventory results directly to the Communication server, based on parameters provided by the Communication server.
  • Save to file: Inventory is done locally and is stored in an XML compressed file with the “.ocs” extension. This file can be imported into the database through the Administration server.

Windows Operating Systems.

OCS Inventory NG Agent for Windows can run as a Windows service automatically at computer startup. It can also function as a stand alone application which can be launched through a login script, an Active Directory GPO, a scheduled task or a shortcut in the Start menu.

Note: We recommend using the service version of the Agent, especially if you plan to use the package deployment feature.


Download and unzip the latest Win32 agent from the Downloads section. This package contains 3 files:

  • OcsAgentSetup.exe: installs the Windows service.
  • OcsAgent.exe: installs the standalone agent for manual inventory (no Windows service).
  • OcsLogon.exe: installs the agent by downloading binaries from Communication server, or runs the agent if already installed. It will install either the service or the standalone version based upon a command line switch. Renaming the file to the DNS or IP of the server will allow it to automatically find the Communication server.

Which version: Service or Standalone ?

The Windows service version will automatically communicate with the OCS-NG system and perform inventories and package deployment based on parameters set on the server. The standalone client is used for computers that cannot communicate with the server, or where the service version is not wanted or allowed.

How does Windows Agent work ?

When the OCS Inventory NG Agent is launched, it queries the Communication server using the HTTP protocol. The server can answer “nothing” (not time for an inventory and no package to deploy), and the agent stops. Otherwise, the server may answer that Agent has to:

  • Send an inventory: the agent retrieves all computer properties and sends them using the HTTP protocol to the server. The server answers this only if the last inventory date in the database is older than the general option “FREQUENCY”, specified in days (see Managing OCS Inventory NG general options.)
  • Discover the network: Agent retrieves all computer properties, scans his subnet for active devices listening on the network, then sends this information using the HTTP protocol to the server. The server answers only if the computer is elected to run IPDISCOVERY (see Using IP discovery feature.)
  • Deploy a package: Agent contacts the deployment server using the HTTPS protocol to get the information file, downloads package fragments from the repository, rebuilds the package and launches it.
Note: The OCS Inventory NG Agent does not listen on the network. It only initiates communications to the server, so you do not have to open inbound ports on a personal firewall. However, you must allow the OCS Inventory NG agent file “OCSInventory.exe” outbound connections to the Communication Server or Deployment Server using either HTTP or HTTPS.


Each time an inventory is done, the Agent writes a configuration file “OCSInventory.dat” to its agent folder where it stores configuration options downloaded from the Communication server.

When launched for the first time, OCS Inventory NG agent will prompt user for the TAG value (if this feature is enabled). Help text displayed in the dialog-box is the one you have entered in Configuring management server. User may enter this value, or leave it blank (you will be able to update this value through the Administration server).

[[Image:|center]]

Then (or otherwise if TAG feature is not enabled), it will do the inventory and send in HTTP inventory results to Communication server.

When the agent is first launched, it will generate and send an inventory only.

How does Windows service work?

Note: You must have Administrator privileges to set up OCS Inventory NG Agent as a service, or you may use OCS Inventory NG Packager to create an installer able to run even if you do not have Administrator privileges. Refer to § Uploading Agent for deployment through launcher “OcsLogon.exe”. or OCS Inventory NG Packager documentation.


  • OCS Inventory NG Agent “OCSInventory.exe” is launched by service “OcsService.exe” every PROLOG_FREQ hours. It keeps trace of the countdown in seconds in file “service.ini” (value TTO_WAIT), so it is the time of EFFECTIVE run.
  • The number of hours to wait is randomized at install time and each time PROLOG_FREQ is changed in Administration Console.
  • It allows not having all agents contacting Communication Server at the same time. The randomization is between 0 and PROLOG_FREQ.

You can adjust these paramaters considering your server load.

When service launch agent, it calls it using the command line switches specified in value “Miscellaneous” of file “service.ini”.

[OCS_SERVICE]
NoProxy=1
Server=my-ocs-server.domain.tld
Pnum=80
Miscellaneous=/DEBUG /NP /server: my-ocs-server.domain.tld /pnum:80
PROLOG_FREQ=10
OLD_PROLOG_FREQ=10
TTO_WAIT=1505

Figure 3: Sample file "service.ini"

As you can see, Service is only a launcher which will run Agent regularly, even if nobody logs in the computer.

Do I have to use service or standalone agent ?

  • You want to have computers inventoried, even if nobody log in ? Use Service version.
  • You want to use package deployment feature ? Use service version. As is, package will be downloaded in background, and logged in user can continue to work.
  • You do not want to set service up or have anything appears in the registry ? Use standalone version. However, deployement of package may take a long time when users log in.

In other words, we recommend using service version.

Manually installing Service version of Agent.

Run “OcsAgentSetup.exe” on client computer..

Agent setup file.png

..and click “Next” button

Agent setup 1.png

Validate license agreement by clicking “I agree” button.

Agent setup 2.png

Fill in OCS Inventory NG Communication server address and port. If you do not wish to use Microsoft Internet Explorer proxy settings (because your proxy requires authentication for example), enable “No Proxy” checkbox. The miscellaneous field allows you to pass the agent other command line arguments (cf Agent’s command line switches). Then click “Next” button.

Agent setup 3.png

Choose destination folder, “C:\Program Files\OCS Inventory Agent” by default, and click “Install” button.

Agent setup 4.png

Click “Close” button to register OCS inventory NG agent service into System.

Agent setup 5.png

Agent is now installed as a service automatically started at system boot under account LocalSystem.

Agent setup 6.png

This is the interactive installation setup. However, this process requires that you launch it under all your computers. Hopefully, this installation can be scripted.

Note: Service Agent setup supports all Agent switches defined in Agent’s command line switches. Enter them into the miscellaneous field.


Service Agent setup “OcsAgentSetup.exe” may be called with some command line parameters:

  • /S to run installation in silent mode, without any user interaction,
  • /UPGRADE to upgrade an existing Service Agent installation,
  • /NOSPLASH to disable splash screen,
  • /NoOcs_ContactLnk to disable Ocs-Contact link in Start Menu,
  • /D= to use an alternate install folder, (must be the last parameter without ["] ie: /D=E:\my install folder)
  • and all Agent’s command line switches, especially /SERVER to specify OCS Inventory NG Communication Server address when using silent installation (see § Agent’s command line switches).

Manually installing standalone Agent (without service).

This way may be usefull on a non network connected computer.

Setup can be run by a normal user, or better by a system administrator.

You just have to run file “OcsAgent.exe /local” to launch OCS Inventory NG agent’s setup. Setup will try to install OCS Inventory NG agent’s files in the folder “C:\ocs-ng” or, if the locally connected user do not have permission to create folder in the root directory, in the folder “ocs-ng” in the user’s temporary directory. Then, it will launch OCS Inventory NG agent.

Agent will then prompt user for folder where to store inventory results.

Agent requesting path.jpg

When launched for the first time, OCS Inventory NG agent will prompt the user for the TAG value User may enter this value, or leave it blank (you will be able to update this value through the Administration server).

[[Image:|center]]

When inventory is finished, agent will display a message showing where the inventory results file has been stored.

[[Image:|center]]

User then just has to send this file to administrator. Administrator will be able to import inventory results into the database through the Administration server.

If you want to run another inventory, you just have to rerun “Ocsinventory.exe /local” from OCS Inventory NG agent’s installation folder.

Note: Standalone Agent setup support in command line all Agent switches defined in § Agent’s command line switches.


Deploying Agent using launcher OcsLogon.exe through Login Script or Active Directory GPO.

The Launcher “OcsLogon.exe” is a small tool able to run inside a login script or an Active Directory GPO. Its purpose is to launch the OCS Inventory NG Agent on client computers, and if the Agent is not yet installed, to set it up.

  • To deploy the Standalone Agent with the launcher, you first must have uploaded the Standalone Agent file “ocsagent.exe” to the server with the Administration Console.
  • To deploy the Service Agent with the launcher, you first must have uploaded the Service Agent file “ocspackage.exe” to the server with the Administration Console. Refer to § Uploading Agent for deployment through launcher “OcsLogon.exe”.

Launcher “OcsLogon.exe” will try to connect by default to the Communication Server using a DNS name “ocsinventory-ng”, as if you open your favorite web browser and enter the URL http://ocsinventory-ng/ocsinventory.

To use a different URL if you cannot add this DNS name, just rename “OcsLogon.exe” with the DNS name or IP address of the Communication Server (for example “ocsinventory.domain.tld.exe” if you have created for your server a DNS record “ocsinventory.domain.tld” or “192.168.1.2.exe” if your server's IP address is 192.168.1.2). Launcher will then try to connect to the DNS name or IP address you have given as its name (http://ocsinventory.domain.tld/ocsinventory or http://192.168.1.2/ocsinventory).

Note: Always use the latest version of OcsLogon.exe. You can get it from the latest package OCSNG_WIN32_AGENT_XX.zip.


Launcher will first check if OCS Inventory NG agent is installed, and if not, will contact Communication Server in HTTP to download latest agent binaries and set up locally on the computer:

  • Standalone Agent in the folder “C:\ocs-ng” by default or, if the locally connected user does not have permission to create folder in the root directory, in the folder “ocs-ng” in the user’s temporary directory. If Standalone agent is already installed, launcher will just run the agent.
  • Service Agent in folder “C:\Program Files\OCS inventory Agent” by default.

To choose between Standalone or Service agent, there is just a command line switch “/INSTALL” to specify if you want to use Service or not. If you add “/INSTALL” command line switch, launcher will use Service Agent. Otherwise, it will use Standalone Agent.

If you want to update Agent, you have to specify in launcher command line version of the new release using the switch /DEPLOY:XXXX, where XXXX is the version of agent, 4031 for version 1.01.

Deploying Agent through Active Directory GPO.

Note: We recommend using service version of Agent if you plan to use package deployment feature.


  • To deploy Standalone Agent with launcher, you need to have uploaded Standalone Agent file “ocsagent.exe” with Administration Console.
  • To deploy Service Agent with launcher, you need to have uploaded Service Agent file “ocspackage.exe” with Administration Console and to use “/INSTALL” command line switch in launcher.

Refer to § Uploading Agent for deployment through launcher “OcsLogon.exe”.


Open “Active Directory users and computers” tool.

Agent setup AD.png

Right click on your Active Directory domain or Organisational Unit and select “Properties”.

[[Image:|center]]

In “Group Policy” tab, create a new policy, or edit existing one.

Note: You can run GPO editor directly by using gpedit.msc command.


You either use Computer policy, or User policy. Computer policy will run at computer startup or User policy will run at user login.

Note: In our example, we will use Computer policy and Startup script. Communication Server address is 192.168.1.2, because we choose to set up Service Agent version. If you choose to use Standalone Agent, it’s better to use User policy and startup script, to allow agent running each time a user log in.


Expand “Computer configuration” tree in left pane and navigate as shown below to “Windows settings” and “Scripts”. Then double click on “Startup” on right pane.

[[Image:|center]]

Click on “Show files” button to display script and executable files usable by computer startup scripts.

[[Image:|center]]

Copy launcher “Ocslogon.exe” or the renamed one (in our example “192.168.1.2.exe”) into this folder to allow its use by computer startup scripts.

[[Image:|center]]

Next close “Startup” folder and click “Add” script button, click “Browse” button to select launcher “OcsLogon.exe” or the renamed one (in our example “192.168.1.2.exe”), and fill in launcher parameters (in our example “/S” for silent installation, “/DEBUG” to enable creating log files, “/NP” to disable use of Internet Explorer proxy settings, “/INSTALL” to deploy Service Agent, “/DEPLOY:4029” to force deployment of version 4029, “/SERVER:192.168.1.2” to use Communication Server at address 192.168.1.2).

[[Image:|center]]

Validate each window to activate Computer Startup script GPO.

[[Image:|center]]

When computer will start (or when user will log in if using User policy), launcher will set up and/or launch OCS Inventory NG agent.

{{Note Launcher OcsLogon.exe may encounter problems accessing the Communication Server if you have configured a proxy with authentication in Microsoft Internet Explorer settings. You can force Launcher to not use proxy with “/NP” command line switch. You can also specify a different IP port to use for Communication server with “/PNUM:XX” command line switch, where XX is the IP port number to use. See § 4.1.5 Agent’s command line switches. }}

Deploying Agent through login script.

Note: We recommend using service version of Agent if you plan to use package deployment feature.


To deploy Standalone Agent with launcher, you need to have uploaded Standalone Agent file “ocsagent.exe” with Administration Console.

To deploy Service Agent with launcher, you need to have uploaded Service Agent file “ocspackage.exe” with Administration Console and to use “/INSTALL” command line switch in launcher OcsLogon.

Refer to § Uploading Agent for deployment through launcher “OcsLogon.exe”.

Copy files “OcsLogon.exe” (or the renamed one) to a shared folder somewhere in your network. This folder must be readable by all your users. Then add a call to “OcsLogon.exe” (or to the renamed one) in your users' login script.

Here is a sample login script.

Warning: Below code requires additional checking for internal lan config, but is functionally.
@echo of
echo Running system inventory, please wait…
REM Call to OCS Inventory NG agent for deployment
REM Using shared folder MY_SHARE on server MY_SERVER
REM Server IP Address is 192.168.1.2 and rename OcsLogon.exe with this ip
REM Install agent using the uploaded package.exe files server
REM Enable debug log with /DEBUG to create OcsLogon.log and computer_name.log
REM Deploy service version of agent using /INSTALL
REM Deploy SILENT agent using /S
REM Deploy No Proxy use using /NP

\\MY_SERVER\MY_SHARE\192.168.1.2.exe /DEBUG /INSTALL /S /NP

echo Done. Thanks a lot.
Sample login script for Windows domain
Note: To be compliant with Windows 9X, you must enclose path to renamed launcher between quotes in the script, otherwise Windows 9X will not use long filename, but sort name like “192~1.exe” and launcher will not be able to find the correct IP address or DNS name.


Put this script named “ocs.bat” for example on your Domain Controler in the folder “%WINDIR%\SYSVOL\Domain\Scripts”, where “%WINDIR%” is generally “C:\WINNT” or “C:\Windows”.

Next, you have to link login script with every users registered in your Active Directory domain. You can do this using “Active Directory users and computers” tool.

[[Image:|center]]

For each user, open his properties and in “Profile” tab, add login script name in “Session login script” field.

[[Image:|center]]

When user log in, launcher will set up and/or launch OCS Inventory NG.


Note: Launcher OcsLogon.exe may encounter problems accessing the Communication Server if you have configured a proxy with authentication in Microsoft Internet Explorer settings. You can force Launcher to not use proxy with “/NP” command line switch. You can also specify a different IP port to use for Communication server with “/PNUM:XX” command line switch, where XX is the IP port number to use. See § 4.1.5 Agent’s command line switches.


Using PSEXEC / PSTOOLS to deploy the Agent

PSEXEC from Microsoft (http://download.sysinternals.com/Files/PsTools.zip) is a great and fast way to install the OCS agents on all Windows computers, you can literally setup most of your computers in a few hours (assuming they are all connected to the network, that is).

Some tips:

PSEXEC is best used together with Domain Logon scripts or Active Directory GPO:

  1. Use the PSEXEC to install on all computers that are currently connected to the network (best used during business hours).
  2. Then add a logon script/GPO as described above to install on computers that were offline the next time they connect to the network.
  3. If you really don't want to use logon script/GPO, you can create and monitor a response file to get a list of computers that were not deployed for any reason, and then rerun PSEXEC just for these computers.

PSEXEC Usage examples:

We assume that the agent setup file is called agentsetup.exe and it was placed on a shared folder accessible to all users.

  • Install on all computers currently logged in your domain:
psexec \\* -s \\Server\NetLogon\agentsetup.exe 
  • Install on a single computer:
psexec \\COMPUTER_NAME -s \\Server\NetLogon\agentsetup.exe
  • Install on all computers using the domain administrator credentials:
psexec \\* -s -u Domain\Administrator -p Password \\Server\NetLogon\agentsetup.exe
  • Install on specific computers (ALL.TXT is a text file that lists target computer names, one per line), using domain administrator credentials:
psexec @ALL.TXT -s -u Domain\Administrator -p Password \\Server\NetLogon\agentsetup.exe

Agent’s command line switches

OCS Inventory NG Agent version 4.0.1.0 or higher includes some command line switches to allow detecting errors.

Once agent is installed, you can run it manually to diagnose problems. Use “C:\ocs-ng\OCSInventory.exe [options]” (with Standalone Agent) or “C:\Program Files\OCS Inventory Agent\OCSInventory.exe [options]” (with Service Agent) command line where [options] may be in the following command line switches.


Agent’s command line switch
Meaning
/server:[server name] Tells agent to connect to server “[server name]”
/np Disable use of proxy defined in Internet Explorer settings.
/pnum:X Specify an IP port X for web communication server. By default, HTTP port 80 is used. You can force use of port 8080 for example with the argument /pnum:8080.
/local run agent in local inventory mode. So agent does not try to connect to Communication server. A file “{hostname}.ocs”, containing inventory results in compressed XML, will be created in agent’s directory.
/file Same as /local, but with interaction with Communication server.
/xml Agent will create a non compressed XML file “{hostname}.xml”, containing inventory results, in his directory. If not used in conjunction with /LOCAL, agent tries to connect to Communication server.
/nosoftware Client does report installed software.
/notag Client does not ask user for TAG value.
/tag:”my tag value” Specify TAG value in command line.
/hkcu Force agent to search for installed software also under HKEY_CURRENT_USER registry hive.
/debug Create a log file “{hostname}.log” in agent’s directory.
/force Force agent to always send inventory results, independently of the FREQUENCY parameter.
/uid Force agent to generate a new deviceid.
/dmi If computer serial number cannot be retrieved with WMI, force agent to use DMI tables while running “BiosInfo.exe” tool. Otherwise agent tries first BIOS functions and then DMI tables.
/biosfunc If computer serial number cannot be retrieved with WMI, force agent to use BIOS functions while running “BiosInfo.exe” tool. Otherwise agent tries first BIOS functions and then DMI tables.
/conf:[filename] Tells agent to use “[filename]” as configuration file. Otherwise it will use default “Ocsinventory.dat” file.
/test Agent only tests HTTP connection to communication server and write a file “ok.ok” if all is good. May be only used with /DEBUG, /NP et /PNUM switches (disable all other switches).
/ipdisc:[network number] Force agent to run IPDISCOVERY feature on network numbered “[network number]” if server ask an inventory. May be used in conjunction with /force to ensure it will run. Cannot be used with /local.
/fastip agent only scan 5 IPs if it is elected as IPDISCOVER host (only usable for debug or test, may not be used in production).

When using launcher “OcsLogon.exe” to deploy agent or run the agent, you can use the following command line switches.


Note: You can also add all switches supported by OCS Inventory NG Agent.



Launcher command line switch
Meaning
/DEPLOY:XXXX Force deployment of a specific agent version XXXX. Use “/DEPLOY:4030” (lastest version) to upgrade agent to version 4.0.3.0.
/INSTALL Tells launcher to set Service Agent up, instead of Standalone Agent.
/URL:[download_url] Tells launcher to download Standalone Agent “ocsagent.exe” or Service Agent “ocspackage.exe” from “[download_url]” (without final filename). Usefull for deploying Agent in mulitple Active Directory domain, but using a single Communication Server.
/NP Disable use of proxy defined in Internet Explorer settings.
/PNUM:X Specify an IP port X for web communication server. By default, HTTP port 80 is used. You can force use of port 8080 for example with the argument /pnum:8080.
/LOCAL run agent in local inventory mode. So agent does not try to connect to Communication server. A file “{hostname}.ocs”, containing inventory results in compressed XML, will be created in agent’s directory.
/NOTAG Client does not ask user for TAG value.
/TAG:”my tag value” Specify TAG value in command line.
/DEBUG Create a log file “{hostname}.log” in agent’s directory.
/FOLDER:[PATH] Tells launcher to set agent up into “[PATH]” installation folder. MUST BE THE LAST COMMAND LINE ARGUMENT.


Compatibility

OS Version Compatibility Works with agent Comments
Windows NT4 YES Windows Agent 4.0.5.4 Not supported by upcoming rearch agent
Windows 95 YES Windows Agent 4.0.5.4 Not supported by upcoming rearch agent
Windows 98, ME YES Windows Agent 4.0.5.4 Not supported by upcoming rearch agent
Windows 2000 YES Windows Agent 4.0.5.4
Windows XP YES Windows Agent 4.0.5.4
Windows Vista Yes Windows Agent 4.0.5.4
Windows Vista 64 bits YES Windows Agent 4.0.5.4 Cannot inventory 64 bits softwares
Windows 7 YES Windows Agent 4.0.5.4
Windows 2000 Server YES Windows Agent 4.0.5.4
Windows 2003 Server YES Windows Agent 4.0.5.4
Windows 2003 Server 64 bits YES Windows Agent 4.0.5.4 Cannot inventory 64 bits softwares
Windows 2008 Server YES Windows Agent 4.0.5.4

Deploying Unix agent in silent mode

Download “OCSNG_LINUX_AGENT_1.01.tar.gz” from OCS Inventory Web Site.

Unpack it.

tar –xvzf OCSNG_LINUX_AGENT_1.01.tar.gz

Run “setup.sh” installer with the following command line arguments:

cd OCSNG_LINUX_AGENT_1.01
sh setup.sh <SETUP DEPENDENCIES> <SERVER ADDRESS> [<SERVER PORT> <TAG VALUE>]

where parameters values are:

  • <SETUP DEPENDENCIES> must be “1” if want to enable automatic setup of missing dependencies, “0” to disable (setup will fail if there is missing dependency).
  • <SERVER ADDRESS> must be the IP address or DNS name of OCS Inventory NG Communication server. If you plan to set agent up in local mode in a non network connected computer, you must set <SERVER ADDRESS> to “local”.
  • <SERVER PORT> may be OCS Inventory NG Communication server port if you’re not using standard HTTP port 80.
  • <TAG VALUE> may be the value of TAG, between quotes.

Command line parameters <SETUP DEPENDENCIES> and <SERVER ADDRESS> are required. The other parameters are optional, but if you wish to set <TAG VALUE>, you must also specify previous optional parameter <SERVER PORT>.


Example:

  • sh setup.sh 1 ocsng.domain.tld will set agent up, installing missing dependencies if needed, and connecting to OCS Inventory NG Communication Server “ocsng.domain.tld”
  • sh setup.sh 0 ocsng.domain.tld 8080 will set agent up, without installing missing dependencies, and connecting to OCS Inventory NG Communication Server “ocsng.domain.tld” on port 8080
  • sh setup.sh 0 192.168.1.2 80 “my tag value” will set agent up, without installing missing dependencies, and connecting to OCS Inventory NG Communication Server “192.168.1.2” on port 80, and setting TAG to “my TAG value”.


Note: Installer writes a log file “ocs_agent_setup.log” in the same directory. If you encounter any error, please refer to this log for detailed error message.