Logmanager Orchestrator

Basically there are two main parts to this solution: first part is software installed on the endpoint (workstation or server) called agent and then second part which is everything that happens on Logmanager side. Only the first part (agent) will be discussed in this documentation.

As mentioned agent called Logmanager Orchestrator is installed on endpoints and it is itself divided into three parts:

• Elastic Filebeat – responsible for collecting and sending data stored in a flat files.
• Elastic Winlogbeat – responsible for collecting and sending native Windows Event Data.
• Logmanager Orchestrator – responsible for managing agents state, connection between agents and Logmanager, pulling config, updating, registering with Logmanager after installation, checking certificate and more.

All components are implemented as Windows Services.

More information regarding Beats agents is available here:

• Filebeat Overview | Filebeat Reference [7.16] | Elastic - https://www.elastic.co/guide/en/beats/filebeat/current/how-filebeat-works.html
• Winlogbeat Overview | Winlogbeat Reference [7.16] | Elastic - https://www.elastic.co/guide/en/beats/winlogbeat/current/_winlogbeat_overview.html

There are more Elastic Beats agents available (example: metricbeats/auditbeats). Logmanager supports all Elastic Beats agents but currently only Filebeat and Winlogbeat can be centrally managed from GUI. In future releases we are planning on adding central management functionality for other Beats agents.

Elastic Beats are a part of open-source software licensed under Apache License 2.0. According to this license, we are able to use the Elastic Beats for commercial purposes.

Elastic Beats are a great software, which offers a lot of functionalities and have been developed and proven for the last few years in countless implementations all over the world. That’s why we decided to not reinvent the wheel but improve it. The main problem with Beats for our purposes is its lack of native central management option and relatively hard configuration. With Logmanager Orchestrator, we were able to deal with those issues.

Of course, we did not forget about filtering, which is applied from the GUI directly to either of Beats agents, so filtered events can be dropped before they are forwarded to Logmanager. We have also added auto-updates (if you choose to use it), certificate checking, and encryption.

All of this is packed together into one convenient MSI package which you can deploy using GPO or SCCM.

Solution architecture details:

• Winlogbeat collects events from Windows Events Store, applies filtering, and forwards messages to Logmanager over port TCP/5044 TLS 1.3.
• Filebeat collects logs from flat files in the Windows OS, applies filtering, and forwards messages to Logmanager over port TCP/5044 TLS 1.3.
• Logmanager Orchestrator connects with Logmanager over HTTPS/443 TLS 1.2, 1.3 and deals with:
  • Registering Orchestrator in Logmanager after installation.
  • Pulling config changes from Logmanager and applying it to Beats Agents (for example: filters).
  • Updating Beats Agents and itself once the update becomes available and auto-update option is enabled.
  • Checking certificate validity (if applied).
  • Changing Beats Agents services state (starting, stopping).
• Logmanager enables central management of Beats Agents and Orchestrator from the GUI (config changes, filters creating and editing, reviewing and changing Beats agents state, etc.).

Another important part of solution architecture is DNS and Windows Registry:

• DNS is used to resolve DNS SRV record to IP address of Logmanager. This approach enables:
  • Agent uses DNS discovery by default to find Logmanager server.
  • Failover config: DNS Failover
  • Logmanager IP change: instead of reconfiguring all agents in your environment in case on Logmanager primary IP change, you can simply update your Logmanager A record.
• Windows Registry is used to store config and change some behavior options of the solution:
  • dns_override_host: DNS SRV override
  • dns_prefix: DNS SRV prefix override
  • log_level: Windows registry keys

If you make any changes to the settings through the registry, you must restart the logmanager-orchestrator-service.

• Windows 10
• Windows 11
• Windows Server 2012 R2
• Windows Server 2016
• Windows Server 2019
• Windows Server 2022

Only Windows operating systems based on 64-bit architecture are supported.

There are no specific application requirements apart from the obvious: open network connection between host and Logmanager. Refer to LM communication matrix for more information: Communication of Logmanager — Logmanager documentation - https://doc.logmanager.cz/manual/lm/en/communication-matrix.html

DNS SRV records set should be set, but it can be skipped if appropriate registry key is set. Refer to: DNS SRV override

To ensure the simplest configuration of endpoints, by default Orchestrator resolves Logmanager server IP address using DNS.

IP address of Logmanager server is automatically detected by DNS SRV query in the following format:

_logmanager._tcp.<our-domain>

You should use only hostname (record A) in SRV record. If you will configure SRV record with IP address instead of a hostname, Orchestrator will fail to connect with Logmanager. You have to make sure your Logmanager server has a proper resolvable hostname configured.

To add A record go to your Windows DNS server and open DNS Manager:

1. From the left side list select Server ‣ Forward Lookup Zones.
2. Right click on <Your_Domain_Name>
3. Click New Host (A or AAAA)…
4. Fill Name field
5. Fill IP Address with IP of your Logmanager instance.
6. Click Add Host.

SRV record must have the following path:

_logmanager._tcp.<our-domain>

To add SRV record go to your Windows DNS server and open DNS Manager.

1. From the left side list select Server ‣ Forward Lookup Zones ‣ Your_Domain_Name.
2. Right click on _tcp.
3. Click Other New Records ‣ Service Location (SRV) ‣ Create Record.

Fill the record form with following information:

• service: _logmanager
• protocol: _tcp
• priority, weight: see DNS Failover
• port number: see notes below
• host offering this service: <hostname (record A) of Logmanager with “.”(dot) at the end!>

Port number in SRV record will not have any effect on agents behavior since they are programmed to use hardcoded port 5044. For old agent (WES) legacy purposes you can set port to 20514 or 20515 (for SSL) but if you are not planning on using old agent you can set this option to anything.

Run this in command prompt:

nslookup
set type=srv
_logmanager._tcp.<name of your AD domain>

An example data return:

> set type=srv
> _logmanager._tcp.example.ad
Server: Unknown
Address: 192.0.2.40

_logmanager._tcp.example.ad
  SRV service location:
   priority       = 0
   weight         = 0
   port           = 20514
   srv hostname   = logmanager.example.ad

The “SRV hostname” is an IP address to which logs will be sent and also the address against which a check for newer versions of Logmanager Orchestrator will be run.

Using DNS SRV record you can configure agent failover – in case of failure of primary Logmanager instance, second instance will be contacted by Orchestrator. This is of course usable only in environments with two or more Logmanager servers.

To configure DNS failover simply add another SRV record with proper priority and weight. To put it simple:

• Lower priority = better
• Higher weight = better

For example, correct failover configuration could look like this:

• Primary SRV record. Hostname: logmanager.example.ad, priority: 0, weight: 100.
• Secondary SRV record. Hostname: logmanager2.example.ad, priority: 0, weight: 0.

Primary SRV record will be contacted first – priorities are the same but Primary SRV record has higher weight than Secondary

In some specific cases you might want to separate your Orchestrator API communication from Logmanager web user interface. Orchestrator API uses by default port 443, which is the same as Logmanager web user interface, because of that, endpoints with Orchestrator installed will also have access to Logmanager web user interface. If you need to restrict access to the Logmanager web user interface, you can use an alternative Orchestrator API port 8444 that only Orchestrator API endpoints have access to.

Or manually via Windows Registry (regedit) - Windows registry keys

Install package is available in menu Sources ‣ Beats Global Config. You can download latest version of Orchestrator by clicking on button Download Logmanager Orchestrator. You can find more specific information here: Beats Global Config

Orchestrator can be installed in several ways, described below.

1. Create a folder on a File Sharing server (e.g. D:\Logmanager) and turn on sharing for this folder (e.g. under name LM$).
   • Rights for folder security and rules for sharing must be set at least to read for authenticated users or for everyone.
   • Copy the installation MSI file to the folder.
2. Create a new Group Policy Object on Domain Controller and link it to the OU which contains endpoints on which the Orchestrator agent should be installed.
   • Right-click on the newly created GPO and select Edit.
   • In GPO editing find the folder Computer Configuration\Policies\Software Settings\Software Installation.
   • Right-click and select option New > Package, and insert the path to the MSI package in the UNC format (e.g. \\servername\LM$\Logmanager-orchestrator-installator.msi).

     The name of the file CANNOT contain spaces!!!

   • Option - To deploy Software, in the following dialog set to Assigned.
3. Once endpoints in the assigned OU receive new Group Policy agent software should be installed. You can manually test this by going to the selected endpoint and running command gpupdate /force. This will force Policy update and installation of the agent.

If for any reason you will have issues with normal installation of MSI package, try running it via CMD with Administrator rights:

1. Open command line with Administrator Rights:
   • Find CMD.exe ‣ Right Click ‣ Run As Administrator
2. Go to folder with MSI package:
   • cd <path_to_executable>
   • Example: cd C:\Installation_Dir\Agent\Logmanager-orchestrator-service-installer.msi
3. Run MSI by typing package name and pressing enter.
4. Follow MSI installation process.

If you wish to install MSI package quietly (without UI) you can do following:

1. Open command line with Administrator Rights:
   • Find CMD.exe ‣ Right Click ‣ Run As Administrator
2. Run:
   • Without logging: msiexec /i <path_to_msi_file> /quiet
   • With logging: msiexec /i <path_to_msi_file> /quiet /l*v <path_and_name_of_log_file>

Example:

cd C:\Installation_Dir\Agent\
msiexec /i logmanager-orchestrator-service-installer.msi /quiet /l*v log.txt

Running this command will install Orchestrator without updater, with installation log created in C:\Installation_Dir\Agent\ folder.

In order to override default installation parameters, create parameters.ini file in the same folder as your MSI.

Example contents of parameters.ini file:

[DNS]
; Use Hostname in case network name resolution is not working.
; Using this parameter during MSI install will set dns_override_host with corresponding value in registry.
; Provided hostname will be checked to make sure it is valid DNS name or IP address.
dns_override_host = logmanager.example.com

; Provide different prefix for SRV record.
; Using this parameter during MSI install will set dns_prefix with corresponding value in registry.
; Provided prefix will be checked to make sure it is valid DNS name.
dns_prefix = logmanager

[Updates]
; Enable or disable Orchestrator auto updates.
; Accepts following values: enabled, disabled
auto_update = enabled

[Network]
; Enable or disable Orchestrator alternative API port 8444.
; Accepts following values: enabled, disabled
alternative_api_port = disabled

This is just an example! Please don’t copy-paste it blindly, use only those parameters you need and comment the rest.

Explanation regarding parameters.ini file:

• It has to be in the same folder as MSI - if it is not present, MSI will use default values.
• It can be used only with following installation types: quiet and GPO.
• Comments start with ; (semi-colon).
• Parameters are provided in format key = value or key=value (without spaces).
• Allowed parameters are:
• • dns_override_host - refer to: DNS SRV override
• • dns_prefix - refer to: DNS SRV prefix override
• • auto_update - refer to: Auto Updates
• • alternative_api_port - refer to: Alternative API Port
• Any other parameter you add to this file will be skipped.

parameters.ini file will not work during UI install! To make use of it choose either quiet (Quiet Installation) or GPO install (GPO Installation).

C:\ProgramFiles\Logmanager\
	- logmanager-orchestrator-service.exe
	- logmanager-orchestrator-updater.exe
	- beats\
		- filebeat\
			- data\
			- logs\
				- Filebeat
				- Filebeat.1
			- LICENSE
			- filebeat.exe
			- filebeat.yml
		- winlogbeat\
			- data\
			- logs\
				- winlogbeat
				- winlogbeat.1
			- LICENSE
			- winlogbeat.exe
			- winlogbeat.yml

Logmanager Orchestrator uses windows registry as a config storage.

Path: HKEY_LOCAL_MACHINE\SOFTWARE\Sirwisa\Logmanager Orchestrator

• uuid: Client-generated id

• assigned_id: Server-generated client id - this id is used for further API communication

• agent_check_inverval: Server-given value in seconds (int) - how often should client sync up with Logmanager. Default interval is 3600 seconds (hour).

• log_level: What level should be used when logging messages: debug ‣ info ‣ warning ‣ error. Default is info.

• validate_server_certificate: Should Orchestrator validate server certificate (default: "disabled"). This option is configured via GUI. Refer to: Beats Global Config

• (Optional) alternative_api_port: Set to “enabled” to use alternative API port 8444 (default: “disabled”).

• (Optional) dns_override_host: What host should be used in DNS discovery when looking for LM (default: _logmanager._tcp.<domain_name>).

• (Optional) dns_prefix: What service should be looked for in DNS discovery (default: logmanager).

Only following variables can be changed by user: log_level, dns_override_host, dns_prefix.

Default log_level should be enough to help you get the Logmanager Orchestrator up and running and diagnose issues (if any). Be careful with changing it to Debug, as it can generate a lot of messages.

Once you apply changes to any registry key, you must restart service “logmanager-orchestrator-service” otherwise changes will not be implemented.

If for whatever reason you do not want your agent to use DNS SRV record for resolving Logmanager IP you can override default agent behavior by setting appropriate registry key.

By default agent will try to resolve following DNS SRV record: _logmanager._tcp.<your_domain_name>.

To change this, add dns_override_host key with value set to Logmanager A record (hostname):

1. Open Registry Editor (regedit.exe).
2. Go to HKEY_LOCAL_MACHINE\SOFTWARE\Sirwisa\Logmanager Orchestrator
3. Right click ‣ New ‣ String Value:
   • Key name: dns_override_host
   • Value name: <Hostname A record>
4. Restart logmanager-orchestrator-service.

This will force agent to connect directly to configured endpoint omitting DNS SRV resolution.

You can also modify registry key to change default DNS SRV prefix.

As mentioned in DNS SRV override, by default Orchestrator will try to resolve DNS SRV record with prefix: _logmanager. You can change that behavior:

1. Open Registry Editor (regedit.exe).
2. Go to HKEY_LOCAL_MACHINE\SOFTWARE\Sirwisa\Logmanager Orchestrator.
3. Right click ‣ New ‣ String Value:
   • Key name: dns_prefix
   • Value name: <new prefix name WITHOUT leading “_”>
4. Restart logmanager-orchestrator-service.

This change will force agent to perform DNS SRV resolution with new prefix. For example:

Default: _logmanager._tcp.example.ad
New: _prefix-logmanager._tcp.example.ad

Information regarding Orchestrator and Beats Agents will be logged to Application channel (Even Viewer ‣ Windows logs ‣ Application folder) with Event ID 1 and Source set to Logmanager Orchestrator. Most common issues are:

• Failing to register the Orchestrator service – usually related to connection issues, lack of or badly configured DNS SRV record. Check if proper communication channels are opened (Communication of Logmanager — Logmanager documentation - https://doc.logmanager.cz/manual/lm/en/communication-matrix.html), DNS SRV record is resolvable or dns override registry key set.
• Services installation failure – try running the installation manually via CMD. Refer to: <Link_to_manual_installation> for more info.
• Specific beats agent logs location: C:\ProgramFiles\Logmanager\Beats<agent_name>\Logs.

If the installation has not been successful, check the System EventLog of the specific workstation / server.

If the installation ended with error 1274 or 1612, the workstation had a problem accessing the network folder:

• It might be due to the improper access rights. GPO software installation is performed by SYSTEM user, make sure it can access shared folder.
• Installation might attempt to start even though network interface is not yet up – in such case machine will be unable to access shared folder. To avoid this issue, Enable following policy in installation GPO: Computer Configuration/Administrative Templates/System/Logon/Always wait for network
• You should also make sure so there is enough time during boot to process the installation GPO. Enable following policy in installation GPO: Computer Configuration/Administrative Templates/System/Group Policy/Startup policy processing wait time + reasonable amount of time (e.g. 45sec)

If the installation ended with error 1001, then it is necessary to run installation with administrator permission.

If you’re having issues with network connectivity between your agent and LM, you can use following command to test it.

logmanager-orchestrator-service.exe ping <host>:port

Port has to be supplied, but Host is optional - in case it is not provided, Ping will resolve LM IP from DNS SRV record or grab it from registry, if dns_override_host key is set.

Full example:

C:\Program Files\LOGmanager>logmanager-orchestrator-service.exe ping 8443
2023/08/21 14:13:15 Info: Resolving logmanager host - using host from registry: 192.168.0.192
Port is OPENED

If given host or port is unavailable, Ping command will try to provide a potential reason.

Starting from version 3.9.8 we have merged two MSI files we had previously (standard Logmanager Orchestrator and Logmanager Orchestrator without self update) into one. Now instead of choosing one MSI or the other depending on your use case, during installation you will be prompted if you want to exclude updater binary from your installation - for example if you wish to disable auto updates on particular endpoint you are installing Logmanager Orchestrator.