DocsSKOOR Windows Agent installation
Introduction
The following guide gives an overview about the installation and functionality of the SKOOR Windows Agent (WinAgent). The software can be downloaded from a SKOOR Engine installation. Open a browser and navigate to the files/agents/windows directory:
The setup program
The WinAgent can be run in two modes: as a Windows service and as a “normal” application. If installed as a service, no user needs to be logged in for it to run. WinAgent will run in the background and will have full permissions to access all relevant data.
If WinAgent runs as an application instead of a service, a user must always be logged in. It will then run with the privileges of the user that is logged in. This mode is useful for Agent Execute Jobs which start GUI applications that cannot be started properly from a service.
Best practice is:
- Run the WinAgent as a Windows service if you want to monitor the Windows Machine (with Agent Process, Agent Network jobs etc.)
- Run the WinAgent as a normal Application if you want to start robot scripts that interact with the GUI
Be aware that not all monitoring data is available when running WinAgent as a normal user. An Agent Process job e.g. would only see the processes of the current user but not all system processes, which could lead to confusion and wrong results. One can always start the WinAgent as an Administrator (right click – Run as administrator) to give the WinAgent access to all data. But one cannot autostart the WinAgent on login with such elevated priviliges.
To be able to install the WinAgent as a Windows service, the setup program must be started as administrator by right clicking and choosing Run as administrator:
The installation program always stops and uninstalls the SKOOR Collector Service (and the SKOOR WinAgent Service of a previous version of the Windows Client in case they would already exist on a target system) before installation starts.
Multi user modes
If the setup is run with administrator privileges, one can choose to install WinAgent for all users (usually under C:\Program Files\Junisphere) or only for the current user (usually under C:\Users\myuser\AppData\Local\Junisphere):
The setup program only offers to install the WinAgent as a Windows service if it should be installed for anyone.
If the setup is not started as an administrator, only the single user mode is supported and the page to choose the mode is not shown.
If the client is installed for all users in C:\Program Files\Junisphere, a normal user cannot change its configuration. To be able to edit the configuration, the WinAgent has to be started as an administrator.
Command line options
The setup program knows about the following command line options:
| Option | Description |
|---|---|
| /service | Install the client as a service. If this option is not given, the client is installed as a normal application |
| /start | Start the client after installation. If it is installed as a service, the service is started, otherwise the application |
| /autorun | Register the application to autorun when a user logs in. This option has no effect, if the client is installed as a service |
| /AllUsers | Install WinAgent for all users under C:\Program Files\Junisphere |
| /CurrentUser | Install WinAgent for the current user under C:\Users\myuser\AppData\Local\Junisphere |
Silent and unattended installation
The setup program supports the /S (S for silent) command line parameter which installs the Windows WinAgent without any user interaction as a service. The SKOOR service is always started after a silent installation.
This silent option allows easy unattended installations and updates with software deployment systems. The other command line options of NSIS installers are supported as well (http://nsis.sourceforge.net/Docs/Chapter3.html#3.2.1) to e.g. override the default installation path (which is “%ProgramFiles%\Junisphere”) with the option /D.
The SKOOR Agent Service
The SKOOR WinAgent runs as a service with the name eRangerService. In this case, WinAgent.exe is only a graphical application that allows controlling and configuring the service if started as an administrator.
The service can be controlled by the WinAgent application or (as any other service) by the service control console. To start this console, hit Windows+R (for “Execute…”) and type services.msc or click Start – Control Panel – Administration – Services.
The service also can be started or stopped on the command line with:
C:\> net start eRangerService C:\> net stop eRangerService
or
C:\> sc start eRangerService C:\> sc stop eRangerService
See the documentation of the sc command for all available options.
Configuration
All runtime configuration settings needed by the SKOOR collector are contained in the file eRangerAgent.ini. There are no other configuration options in the registry (besides the registration of the program itself in Windows). Copying the eRangerAgent.ini file from one WinAgent to another one is enough to replicate all configuration settings.
The configuration file must be kept in the same directory as the executables.
WinAgent can also be started without any configuration file at all. Default values (as with a new installation) will be used in this case.
WinAgent GUI configuration
The easiest way to configure the SKOOR WinAgent is to use the Windows GUI. Click on the configuration button in the tool bar or choose “Configuration…” from the file menu.
The names in italic at the end of the option descriptions underneath are the names used in the configuration file eRangerAgent.ini.
Network settings
| Setting | Description |
|---|---|
| Listen on port | Port on which the WinAgent listens for incoming connections (52998 by default) |
| Username | If a username is specified, this username is used for authentication. This means that the SKOOR collector must pass valid credentials to successfully make requests to the agent. |
| Password | Password used for authentication |
| SSL | If this option is set, the communication is encrypted with ssl |
| Keep-alive | If this option is set, TCP connections from the collector are not disconnected after the request has been received by the agent. The agent can reuse the same TCP connection for many requests. If the connection is broken, the agent opens a new connection without losing data. Setting this option may be useful if establishing a new TCP connection is very expensive or slow (i.e. if the WinAgent is in the internet or on a very slow line). Normally, this option needs not to be set. keep_alive (0 | 1) |
Authorized hosts
Only SKOOR collectors (hosts) with IPs in this list are allowed to connect. If this list is empty, all IPs are allowed to connect.
authorized_host (multiple values possible)
Log settings
These settings configure the logging of the eRanger service.
| Setting | Description |
|---|---|
| Write logfile | Enables/disables logging |
| Logfile path | Path of the logfile. If WinAgent does not run as a service, the user that runs the WinAgent must have permission to write to this location (which is not always the case for the default C:\Program Files\Junisphere… path). log_file_path (absolute path) |
| Loglevel | Sets the log level (Debug > Info > Warning > Error) |
| Truncate at size | If the file grows larger then this value, the file is truncated. max_log_size (size in KB) |
Filetransfer options
This tab sets the permissions to send (Agent fetchfile) and receive (Agent putfile) files to/from the agent.
| Setting | Description |
|---|---|
| Allow files to be received | Files can be received with Client Putfile jobs |
| Allowed targets | Files received from agents can be stored to these target locations. The wildcard characters * and ? can be used. receive_file (absolute path, multiple values possible) |
| Allow files to be sent | Files can be sent with Client Fetchfile jobs. |
| File allowed to be sent | Files from these locations can be fetched by the agent. The wildcards characters * and ? can be used. send_file (absolute path, multiple values possible) |
Do not forget to add an entry to the list with the 
button.
If you try to get or put a file which is not in the list or if sending/receiving functionality is disabled completely, an error message will be sent to the agent and displayed within SKOOR.
Run programs
These settings control if and which programs can be executed on the agent.
| Setting | Description |
|---|---|
| Allow to run programs | Enable this option to allow programs to be run. |
| Programs allowed | Programs in this list are allowed to be executed by the agent. The wildcard characters * and ? can be used. executable_program (absolute path, multiple values possible) |
| Local Windows User | If WinAgent runs as a service, all programs are executed under this Windows user. The username can be given in UPN format if it must contain the domain part (user@domain). If the username is left empty, the programs are executed in the context of the service-owner, the WinAgent is running on. This is normally the LocalSystem account. Applications that use a GUI may not work as expected (see also chapter 5.2). local_windows_user (username) |
| Password | Password for the user. The password is stored in encrypted form in the configuration file. |
| Default Process timeout | Started processes will be killed after the given timeout (in seconds) if they are still running. This value can be overridden by setting a timeout value in the execute job. default_execute_timeout (number in seconds). If this value is 0, the process is not killed at all |
Do not forget to add an entry to the list with the 
button.
If you try to execute a program which is not in the list or if the execution is disabled completely, an error message will be sent to the agent and displayed in SKOOR.
Service and Autorun control
This tab allows to install, uninstall and start/stop the SKOOR collector service. All these operations can also be done in the service control (see chapter 3). WinAgent must be started as Administrator to be able to control the service.
If the Start the eRanger WinAgent after login (all users) checkbox is checked, WinAgent.exe is registered as an autorun program for all users in the registry under:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Run
This option is visible if the WinAgent has been installed for all users and has been started as an Administrator. If the WinAgent is started as a normal User, the check box is labelled with Start the eRangerWinAgent after login (current user). If it is selected, the WinAgent is registered as an autorun program under:
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run
With both options, the WinAgent is then started at login and run in the background.
Issues
Administrator privileges
The SKOOR WinAgent needs administrator privileges to read all performance data from the operating system (e.g. to see all processes from all users etc.). If reliable monitoring data shall be collected and the client cannot be started as a service (which is recommended for this use case) the user has to start the WinAgent as an administrator (right click – Run as administrator).
If the client is installed as a service, WinAgent must be started as an administrator to be able to control the service. Use the built-in Windows service control otherwise.
If the app is installed for all users in C:\Program Files\Junisphere, a normal user cannot change the configuration because he has no permission to write to the file C:\Program Files\Junisphere\eRangerAgent.ini). To be able to edit the configuration, WinAgent has to be started as an administrator.
Starting GUI applications from the agent
Services are not allowed to use the graphical user interface in Windows. If GUI applications (like EEM robot scripts) shall be started by the SKOOR WinAgent on Windows, the agent must be started as a normal application and not as a service. To be sure that the WinAgent runs as an application, uninstall the service (if it is installed).