Chat now with support
Chat with Support

syslog-ng Premium Edition 6.0.22 - Administrator Guide for syslog-ng Agent for Windows

About this document

This guide is a work-in-progress document with new versions appearing periodically.

The latest version of this document can be downloaded from the syslog-ng Documentation page.

Summary of changes

  • Starting from syslog-ng Agent 6.0.20, Windows Server 2008 and Windows 7 are not supported.

Feedback

Any feedback is greatly appreciated, especially on what else this document should cover. General comments, errors found in the text, and any suggestions about how to improve the documentation is welcome at bb-pub-documentation@quest.com.

Introduction

This chapter describes how to install and configure the syslog-ng Agent on Microsoft Windows hosts.

The syslog-ng Agent for Windows is a log collector and forwarder application for the Microsoft Windows platform. It collects the log messages of the Windows-based host and forwards them to a syslog-ng server using regular or TLS-encrypted TCP connections.

The features and restrictions of the syslog-ng Agent are summarized below:

  • Reads messages from eventlog containers and log files.

  • Transfers log messages using TCP.

  • Supports TLS encryption.

  • Authenticates the server using X.509 certificates. Mutual authentication is also supported.

  • The format of eventlog messages can be customized using macros.

  • Supports multiple destinations both in parallel and fail-over modes.

  • Can be managed from a domain controller using group policies.

  • Only basic filtering is supported by the agent, message segmenting, parsing, and classification is not.

  • Note that the log messages on Windows come from files — either eventlog containers or custom log files — which are already stored on the hard disk, so syslog-ng Agent for Windows does not use additional disk buffering.

Supported operating systems

The central syslog-ng server cannot be installed on Microsoft Windows platforms. The syslog-ng Agent for Windows is capable of forwarding log messages to the central syslog-ng server. It is part of the syslog-ng PE, and is licensed together with it.

The syslog-ng Agent application supports the following operating systems. Unless explicitly noted otherwise, the subsequent releases of the platform (for example, Windows Server 2019 R2 and its service packs in case of Windows Server 2019) are also supported.

  • Microsoft Windows Server 2012 (x86_64)

  • Microsoft Windows Server 2016 (x86_64)

  • Microsoft Windows Server 2019 (x86_64)

  • Microsoft Windows 8 (x86 and x86_64)

  • Microsoft Windows 10 (x86 and x86_64)

 NOTE:

The syslog-ng Agent for Windows application supports the XML-based eventlog format and offers full support for 64-bit operating systems.

Installing the syslog-ng Agent

The syslog-ng Agent for Windows application can be installed in standalone mode on independent hosts. If your hosts are members of a domain, you can install the syslog-ng agent on the domain controller and configure them globally.

 NOTE:

The syslog-ng Agent for Windows application is configured usually using its MMC snap-in (when managed globally from the domain controller or when configuring it in standalone mode). However, it is also possible to use an XML-based configuration file. For details, see the section called “Using an XML-based configuration file”.

 Caution:

If you are using an XML configuration file, or you have installed syslog-ng Agent with an XML configuration file, it is not possible to use the MMC snap-in for configuring the syslog-ng Agent.

Installer types: 

  • syslog-ng-agent-<version>-setup.exe is the general installer. This installs an agent that can be configured with a local configuration, XML configuration file and can receive configuration from domain group policy. The installer contains both the 32bit and 64bit versions of syslog-ng Agent.

  • syslog-ng-agent-nosnapin-<version>-setup.exe is a special installer. .NET environment is not required for it. This installs an agent that can only be configured with an XML configuration file, and can receive configuration from domain group policy. The installer contains both the 32bit and 64bit versions of syslog-ng Agent.

  • syslog-ng-agent-setup-<version>-<amd64/i386>.msi is an MSI installer for domain clients, installing by group policy.

Procedure 2.1. Installing the syslog-ng Agent in standalone mode

Purpose: 

The syslog-ng Agent for Windows application can be installed in standalone mode on independent hosts. If your hosts are members of a domain, install the syslog-ng Agent on the domain controller, as described in the section called “Installing the syslog-ng Agent on the domain controller and the hosts of a domain”. The syslog-ng Agent requires about 30 MB hard disk space.

To install the syslog-ng Agent in standalone mode, complete the following steps:

 NOTE:

The regular .exe installer of syslog-ng Agent for Windows requires the Microsoft .NET Framework version 3.5 or 4.0. This package is usually already installed on most hosts. If it is not, you can download the .NET package here.

The nosnapin and the .msi version of the installer does not install the graphical MMC snapin of syslog-ng Agent, and does not require the .NET Framework.

Steps: 

  1. Start the installer. Run the syslog-ng-agent-<versionnumber>-setup.exe file.

    		 NOTE:

    Installing the syslog-ng Agent requires administrator privileges.

  2. Read the End User License Agreement and select I Agree.

  3. Select the destination folder where you want to install the syslog-ng Agent for Windows application, then select Next.

  4. Select Standalone mode, then click Next.

    Figure 2.1. Installing in Standalone mode

    Installing in Standalone mode

  5. The installer automatically opens the configuration interface of the syslog-ng Agent. As a minimum, you must set the IP address of the destination server, and the agent will automatically start sending eventlog messages to your central log server from the Application, Security, and System eventlog containers.

    		 NOTE:

    The installation is completed only after you close the configuration interface. For details on how to modify the configuration later, see Procedure 3.1, “Configuring a standalone syslog-ng Agent”.

Installing the syslog-ng Agent on the domain controller and the hosts of a domain

The syslog-ng Agent for Windows application can be installed on the domain controller and the members of a domain from the domain controller, and configured globally using group policies. The syslog-ng Agent requires about 30 MB hard disk space.

 NOTE:

The .msi version of the installer does not install the MMC configuration snap-in of the agent, therefore the .msi installer does not require the .NET framework.

Procedure 2.2. Installing the syslog-ng Agent on the domain controller and the hosts of a domain

Purpose: 

To install the syslog-ng Agent application on the domain controller and the hosts of a domain, complete the following steps.

This procedure assumes that you install the syslog-ng Agent on the domain controllers in standalone mode, and configure the domain hosts from each domain controller.

 NOTE:

To configure the syslog-ng Agent from domain controllers, you need to install the syslog-ng Agent in standalone mode on at least one domain controller. You can then export the configuration of syslog-ng Agent from the first domain controller and import it to other domain controllers, or you can configure an agent group policy on the other domain controllers, and install syslog-ng Agent in domain mode.

 NOTE:

By default, the syslog-ng Agent for Windows application sends messages as follows:

  • From eventlog sources, the syslog-ng Agent application sends only messages that are created after the agent has been installed.

  • From file sources, it sends the entire content of the file.

Steps: 

  1. Download both the Microsoft Installer (.msi) version and the executable (.exe) version of the syslog-ng Agent installer to the domain controller host. Make sure to download the executable that includes the MMC snap-in module. Note that separate .msi installers are available for 32-bit and 64-bit operating systems.

    		 NOTE:

    Installing the syslog-ng Agent requires administrator privileges, but configuring the related group policies on the domain controller requires domain administrator or higher (for example enterprise administrator) privileges.

  2. Install the syslog-ng Agent application to your domain controllers using the .exe installer.

    		 NOTE:

    The regular .exe installer of syslog-ng Agent for Windows requires the Microsoft .NET Framework version 3.5 or 4.0. This package is usually already installed on most hosts. If it is not, you can download the .NET package here.

    The nosnapin and the .msi version of the installer does not install the graphical MMC snapin of syslog-ng Agent, and does not require the .NET Framework.

    In some rare cases, the syslog-ng Agent service does not start after the installation and you receive the following error message: "Error 1 : Incorrect Function.". In this case, open a command prompt and run the gpupdate /force command.

    • Navigate to Start > Control Panel > Administrative Tools > Group Policy Management.

    • Select and edit the Group Policy object you want to add the syslog-ng Agent configuration to. Alternatively, you can create a new group policy object as well.

  5. Select Computer Configuration, right-click on Software Settings, and select New > Package.

  6. Navigate to the syslog-ng Agent for Windows .msi installer and select Open.

  7. Select Assigned, then OK.

  8. Select Computer Configuration > syslog-ng Agent Settings and configure the syslog-ng Agent. The members of the domain will use this configuration.

    Figure 2.2. syslog-ng Agent Settings

    syslog-ng Agent Settings

  9. The syslog-ng Agent for Windows application will be automatically installed on the members of the domain when they are next rebooted.

    		 NOTE:

    If you do not want to install the syslog-ng Agent automatically from the domain controller, skip Steps 5-7, complete Step 8, then install the syslog-ng-agent-nosnapin-<versionnumber>-setup.exe file manually on the members of the domain. This method is useful if you do not want to install the syslog-ng Agent on every host of the domain.

  10. After the members of the domain have been rebooted, execute the gpupdate command on the members of the domain. The syslog-ng Agent for Windows application will receive its configuration during the group policy update, and start processing log messages accordingly.

Procedure 2.3. Installing the MSI package of syslog-ng Agent into a custom folder

Purpose: 

The .msi installer package of syslog-ng Agent can be modified to install the syslog-ng Agent application into a custom folder.

Steps: 

When installing the syslog-ng Agent application from the command line, execute the following command to specify a custom installation folder: msiexec /i syslog-ng-agent-setup-<version>-<amd64/i386>.msi INSTDIR=C:\<path-to-custom-folder>\

Otherwise, complete the following steps to modify the .msi package.

  1. Download the Orca MSI editor.

  2. Start Orca and load the syslog-ng-agent-setup-<version>-<amd64/i386>.msi file to modify.

  3. Select Transform > New Transform.

  4. Add the INSTDIR property to the Property Table, and set its value to the full path of the folder where you want to install the syslog-ng Agent application.

  5. Select Transform > Generate Transform and save the modifications into a .mst file.

  6. Close the Orca MSI Editor.

  7. Select Start > Control Panel > Administrative Tools > Active Directory Users and Computers and edit the Group Policy object that contains the syslog-ng Agent configuration.

  8. Add the saved .mst package as a modification to the syslog-ng Agent .msi package.

Procedure 2.4. Uninstalling syslog-ng Agent

To uninstall the syslog-ng Agent application, complete the following steps. To uninstall syslog-ng Agent from the command-line, see Procedure 2.5, “Uninstalling syslog-ng Agent in silent mode”.

  1. Navigate to the installation directory of syslog-ng Agent.

  2. Start the uninstall.exe file.

  3. Follow the on-screen instructions.

Procedure 2.5. Uninstalling syslog-ng Agent in silent mode

To uninstall the syslog-ng Agent application from the command-line, complete the following steps. To uninstall syslog-ng Agent using the graphical interface, see Procedure 2.4, “Uninstalling syslog-ng Agent”.

  1. Start a command prompt and navigate to the installation directory of syslog-ng Agent.

    • To uninstall syslog-ng Agent and delete its configuration from the registry, execute the uninstall.exe /S /DELCONF command.

    • To uninstall syslog-ng Agent, without deleting its configuration, execute the uninstall.exe /S command.

Silent installation

The syslog-ng Agent for Windows application can be installed in silent mode as well, without requiring any user interaction. The various installer options can be specified as command-line options. Using the /S option is required. The following options are available.

 Caution:

Write all options in uppercase.

/D=<path>

Install the syslog-ng Agent into the specified folder. Do not use quotes ('') or double-quotes ("") around the folder name, even if it contains whitespace characters.

 Caution:

If you use the /D option, make sure that this is the last option in the command-line. For example: syslog-ng-agent-nosnapin-<version>-setup.exe /S /XMLCONFIG=c:\test.xml /LOCALUPGRADE /D=c:\Program Files\agent\

/LOCAL

Install syslog-ng Agent in standalone mode. This is the default installation mode of the syslog-ng Agent. When using this option, you can also set the following two options:

  • /GPOUPGRADE: Upgrade all GPO configuration having syslog-ng Agent settings during the installation.

    		 Caution:

    Use it only on a domain controller.

  • /LOCALUPGRADE: Upgrade local settings.

    		 NOTE:

    If syslog-ng Agent uses only local configuration and you do not specify this option, it is possible that syslog-ng Agent will not start while you are upgrading its local configuration by opening local configuration with syslog-ng agent MMC snap-in.

/NOMENU

Do not add entries about syslog-ng Agent to the Start menu.

/NOUPGRADE

The installer does not perform upgrade during the installation (default). Use it if the configuration comes from GPO or you are using XML configuration and you do not want to upgrade it (in this case, agent will upgrade it temporarily after starting).

/REMOTE

Install syslog-ng Agent in domain mode.

/S

Start the installer in silent mode. This option is required for the silent installation.

/XMLCONFIG=

Use the specified XML configuration file for the configuration of syslog-ng Agent. When using this option, you can also set the following option:

  • /XMLUPGRADE: Upgrade XML configuration during the installation if XML configuration file is used.

The upgrade operation will be only performed if upgrading is really needed for the specified configuration. For example: If there is no configuration version switching between the current and the previous version of the syslog-ng Agent (for example when upgrading from version 3.0.7 to version 3.0.8) the local settings will not be upgraded even you specify the /LOCALUPGRADE option.

The /LOCAL, /XMLCONFIG, and /REMOTE options conflict with each other. If you specify more than one of them, then /REMOTE takes precedence over the other two options, and /XMLCONFIG takes precedence over the /LOCAL option.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating