diff --git a/installation/windows.md b/installation/windows.md index af13a3480..736717738 100644 --- a/installation/windows.md +++ b/installation/windows.md @@ -1,12 +1,18 @@ # Windows -Fluent Bit is distributed as **fluent-bit** package for Windows and as a [Windows container on Docker Hub](docker.md). Fluent Bit has two flavours of Windows installers: a ZIP archive (for quick testing) and an EXE installer (for system installation). +Fluent Bit is distributed as the `fluent-bit` package for Windows and as a +[Windows container on Docker Hub](docker.md). Fluent Bit provides two Windows +installers: a `ZIP` archive and an `EXE` installer. -Not all plugins are supported on Windows: the [CMake configuration](https://github.com/fluent/fluent-bit/blob/master/cmake/windows-setup.cmake) shows the default set of supported plugins. +Not all plugins are supported on Windows. The +[CMake configuration](https://github.com/fluent/fluent-bit/blob/master/cmake/windows-setup.cmake) +shows the default set of supported plugins. ## Configuration -Make sure to provide a valid Windows configuration with the installation, a sample one is shown below: +Provide a valid Windows configuration with the installation. + +The following configuration is an example: ```python [SERVICE] @@ -75,15 +81,16 @@ Make sure to provide a valid Windows configuration with the installation, a samp ## Migration to Fluent Bit -From version 1.9, `td-agent-bit` is a deprecated package and was removed after 1.9.9. The correct package name to use now is `fluent-bit`. +For version 1.9 and later, `td-agent-bit` is a deprecated package and was removed +after 1.9.9. The correct package name to use now is `fluent-bit`. -## Installation Packages +## Installation packages The latest stable version is 3.2.4. -Each version is available via the following download URLs. +Each version is available from the following download URLs. -| INSTALLERS | SHA256 CHECKSUMS | -| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| INSTALLERS | SHA256 CHECKSUMS | +|----------- | ---------------- | | [fluent-bit-3.2.4-win32.exe](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-win32.exe) | [26b5293833bd777656b087c99293312bdc332cd7d3410c5ce9e37940f716c4d4](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-win32.exe.sha256) | | [fluent-bit-3.2.4-win32.zip](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-win32.zip) | [cd6a7a3202f908464b7e037110c4b13ba13c9a1c222feef103881e3d3f8e1497](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-win32.zip.sha256) | | [fluent-bit-3.2.4-win64.exe](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-win64.exe) | [61f5e1dcd5a8dd446020fb6d9b6ca2d42e143c94f7455df0296f26bcfc808b10](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-win64.exe.sha256) | @@ -91,7 +98,8 @@ Each version is available via the following download URLs. | [fluent-bit-3.2.4-winarm64.exe](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-winarm64.exe) | [acc841c1fbdaa4ab7f95b0f19a566f886fcf1a0dc6c724e9fa9263de5c6d7e3a](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-winarm64.exe.sha256) | | [fluent-bit-3.2.4-winarm64.zip](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-winarm64.zip) | [46f7f259a7134ba1609bca97504092dc68bf3eebd8bc009041c34a24b17eef0e](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-winarm64.zip.sha256) | -**Note these are now using the Github Actions built versions, the legacy AppVeyor builds are still available (AMD 32/64 only) at releases.fluentbit.io but are deprecated.** +These are now using the Github Actions built versions. Legacy AppVeyor builds are +still available (AMD 32/64 only) at releases.fluentbit.io but are deprecated. MSI installers are also available: @@ -99,50 +107,52 @@ MSI installers are also available: - [fluent-bit-3.2.4-win64.msi](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-win64.msi) - [fluent-bit-3.2.4-winarm64.msi](https://packages.fluentbit.io/windows/fluent-bit-3.2.4-winarm64.msi) -To check the integrity, use `Get-FileHash` cmdlet on PowerShell. +To check the integrity, use the `Get-FileHash` cmdlet for PowerShell. -```powershell +```text copy PS> Get-FileHash fluent-bit-3.2.4-win32.exe ``` -## Installing from ZIP archive +## Installing from a ZIP archive -Download a ZIP archive from above. There are installers for 32-bit and 64-bit environments, so choose one suitable for your environment. +1. Download a ZIP archive. Choose the suitable installers for your 32-bit or 64-bit + environments. -Then you need to expand the ZIP archive. You can do this by clicking "Extract All" on Explorer, or if you're using PowerShell, you can use `Expand-Archive` cmdlet. +1. Expand the ZIP archive. You can do this by clicking **Extract All** in Explorer + or `Expand-Archive` in PowerShell. -```powershell -PS> Expand-Archive fluent-bit-3.2.4-win64.zip -``` + ```text + PS> Expand-Archive fluent-bit-3.2.4-win64.zip + ``` -The ZIP package contains the following set of files. + The ZIP package contains the following set of files. -``` -fluent-bit -├── bin -│ ├── fluent-bit.dll -│ └── fluent-bit.exe -│ └── fluent-bit.pdb -├── conf -│ ├── fluent-bit.conf -│ ├── parsers.conf -│ └── plugins.conf -└── include - │ ├── flb_api.h - │ ├── ... - │ └── flb_worker.h - └── fluent-bit.h -``` + ```text + fluent-bit + ├── bin + │ ├── fluent-bit.dll + │ └── fluent-bit.exe + │ └── fluent-bit.pdb + ├── conf + │ ├── fluent-bit.conf + │ ├── parsers.conf + │ └── plugins.conf + └── include + │ ├── flb_api.h + │ ├── ... + │ └── flb_worker.h + └── fluent-bit.h + ``` -Now, launch cmd.exe or PowerShell on your machine, and execute `fluent-bit.exe` as follows. +1. Launch `cmd.exe` or PowerShell on your machine, and execute `fluent-bit.exe`: -```powershell -PS> .\bin\fluent-bit.exe -i dummy -o stdout -``` + ```text + PS> .\bin\fluent-bit.exe -i dummy -o stdout + ``` -If you see the following output, it's working fine! +The following output indicates Fluent Bit is running: -```powershell +```text PS> .\bin\fluent-bit.exe -i dummy -o stdout Fluent Bit v2.0.x * Copyright (C) 2019-2020 The Fluent Bit Authors @@ -161,41 +171,49 @@ Fluent Bit v2.0.x [3] dummy.0: [1561684388.441405800, {"message"=>"dummy"}] ``` -To halt the process, press CTRL-C in the terminal. +To halt the process, press `Control+C` in the terminal. -## Installing from EXE installer +## Installing from the EXE installer -Download an EXE installer from above. It has both 32-bit and 64-bit builds. Choose one which is suitable for you. +1. Download an EXE installer for the appropriate 32-bit or 64-bit build. +1. Double-click the EXE installer you've downloaded. The installation wizard starts. -Double-click the EXE installer you've downloaded. The installation wizard will automatically start. + ![Installation wizard screenshot](<../.gitbook/assets/windows\_installer (1) (1).png>) -![Installation wizard screenshot](<../.gitbook/assets/windows\_installer (1) (1).png>) +1. Click **Next** and finish the installation. By default, Fluent Bit is installed + in `C:\Program Files\fluent-bit\`. -Click Next and proceed. By default, Fluent Bit is installed into `C:\Program Files\fluent-bit\`, so you should be able to launch fluent-bit as follows after installation. +You should be able to launch Fluent Bit using the following PowerShell command:. -```powershell +```text PS> C:\Program Files\fluent-bit\bin\fluent-bit.exe -i dummy -o stdout ``` ### Installer options -The Windows installer is built by \[`CPack` using NSIS([https://cmake.org/cmake/help/latest/cpack\_gen/nsis.html](https://cmake.org/cmake/help/latest/cpack\_gen/nsis.html)) and so supports the [default options](https://nsis.sourceforge.io/Docs/Chapter3.html#3.2.1) that all NSIS installers do for silent installation and the directory to install to. +The Windows installer is built by +[`CPack` using NSIS](https://cmake.org/cmake/help/latest/cpack_gen/nsis.html) +and supports the [default NSIS options](https://nsis.sourceforge.io/Docs/Chapter3.html#3.2.1) +for silent installation and install directory. To silently install to `C:\fluent-bit` directory here is an example: -```powershell +```text PS> /S /D=C:\fluent-bit ``` -The uninstaller automatically provided also supports a silent un-install using the same `/S` flag. This may be useful for provisioning with automation like Ansible, Puppet, etc. +The uninstaller also supports a silent uninstall using the same `/S` flag. +This can be used for provisioning with automation like Ansible, Puppet, and so on. -## Windows Service Support +## Windows service support -Windows services are equivalent to "daemons" in UNIX (i.e. long-running background processes). Since v1.5.0, Fluent Bit has the native support for Windows Service. +Windows services are equivalent to daemons in UNIX (long-running background +processes). +For v1.5.0 and later, Fluent Bit has native support for Windows services. -Suppose you have the following installation layout: +For example, you have the following installation layout: -``` +```text C:\fluent-bit\ ├── conf │ ├── fluent-bit.conf @@ -207,15 +225,16 @@ C:\fluent-bit\ └── fluent-bit.pdb ``` -To register Fluent Bit as a Windows service, you need to execute the following command on Command Prompt. Please be careful that a single space is required after `binpath=`. +To register Fluent Bit as a Windows service, execute the following command on +at a command prompt. A single space is required after `binpath=`. -```powershell -% sc.exe create fluent-bit binpath= "\fluent-bit\bin\fluent-bit.exe -c \fluent-bit\conf\fluent-bit.conf" +```text +sc.exe create fluent-bit binpath= "\fluent-bit\bin\fluent-bit.exe -c \fluent-bit\conf\fluent-bit.conf" ``` -Now Fluent Bit can be started and managed as a normal Windows service. +Fluent Bit can be started and managed as a normal Windows service. -```powershell +```text % sc.exe start fluent-bit % sc.exe query fluent-bit SERVICE_NAME: fluent-bit @@ -224,45 +243,47 @@ SERVICE_NAME: fluent-bit ... ``` -To halt the Fluent Bit service, just execute the "stop" command. +To halt the Fluent Bit service, use the `stop` command. -```powershell -% sc.exe stop fluent-bit +```text +sc.exe stop fluent-bit ``` To start Fluent Bit automatically on boot, execute the following: -``` -% sc.exe config fluent-bit start= auto +```text +sc.exe config fluent-bit start= auto ``` -### \[FAQ] Fluent Bit fails to start up when installed under `C:\Program Files` +## FAQs -Quotations are required if file paths contain spaces. Here is an example: +### Fluent Bit fails to start up when installed under `C:\Program Files` -``` -% sc.exe create fluent-bit binpath= "\"C:\Program Files\fluent-bit\bin\fluent-bit.exe\" -c \"C:\Program Files\fluent-bit\conf\fluent-bit.conf\"" +Quotations are required if file paths contain spaces. For example: + +```text +sc.exe create fluent-bit binpath= "\"C:\Program Files\fluent-bit\bin\fluent-bit.exe\" -c \"C:\Program Files\fluent-bit\conf\fluent-bit.conf\"" ``` -### \[FAQ] How can I manage Fluent Bit service via PowerShell? +### Can you manage Fluent Bit service using PowerShell? Instead of `sc.exe`, PowerShell can be used to manage Windows services. Create a Fluent Bit service: -```powershell +```text PS> New-Service fluent-bit -BinaryPathName "C:\fluent-bit\bin\fluent-bit.exe -c C:\fluent-bit\conf\fluent-bit.conf" -StartupType Automatic ``` Start the service: -```powershell +```text PS> Start-Service fluent-bit ``` Query the service status: -```powershell +```text PS> get-Service fluent-bit | format-list Name : fluent-bit DisplayName : fluent-bit @@ -277,82 +298,88 @@ ServiceType : Win32OwnProcess Stop the service: -```powershell +```text PS> Stop-Service fluent-bit ``` Remove the service (requires PowerShell 6.0 or later) -```powershell +```text PS> Remove-Service fluent-bit ``` ## Compile from Source -If you need to create a custom executable, you can use the following procedure to compile Fluent Bit by yourself. +If you need to create a custom executable, use the following procedure to +compile Fluent Bit by yourself. ### Preparation -First, you need Microsoft Visual C++ to compile Fluent Bit. You can install the minimum toolkit by the following command: +1. Install Microsoft Visual C++ to compile Fluent Bit. You can install the minimum + toolkit using the following command: -```powershell +```text PS> wget -o vs.exe https://aka.ms/vs/16/release/vs_buildtools.exe PS> start vs.exe ``` -When asked which packages to install, choose "C++ Build Tools" (make sure that "C++ CMake tools for Windows" is selected too) and wait until the process finishes. +1. Choose `C++ Build Tools` and `C++ CMake tools for Windows` and wait until the process finishes. -Also you need to install flex and bison. One way to install them on Windows is to use [winflexbison](https://github.com/lexxmark/winflexbison). +1. Install flex and bison. One way to install them on Windows is to use + [winflexbison](https://github.com/lexxmark/winflexbison). -```powershell -PS> wget -o winflexbison.zip https://github.com/lexxmark/winflexbison/releases/download/v2.5.22/win_flex_bison-2.5.22.zip -PS> Expand-Archive winflexbison.zip -Destination C:\WinFlexBison -PS> cp -Path C:\WinFlexBison\win_bison.exe C:\WinFlexBison\bison.exe -PS> cp -Path C:\WinFlexBison\win_flex.exe C:\WinFlexBison\flex.exe -``` + ```text + PS> wget -o winflexbison.zip https://github.com/lexxmark/winflexbison/releases/download/v2.5.22/win_flex_bison-2.5.22.zip + PS> Expand-Archive winflexbison.zip -Destination C:\WinFlexBison + PS> cp -Path C:\WinFlexBison\win_bison.exe C:\WinFlexBison\bison.exe + PS> cp -Path C:\WinFlexBison\win_flex.exe C:\WinFlexBison\flex.exe + ``` -Add the path `C:\WinFlexBison` to your systems environment variable "Path". [Here's how to do that](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/). +1. Add the path `C:\WinFlexBison` to your systems environment variable `Path`. + [Here's how to do that](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/). -It is important to have installed OpenSSL binaries, at least the library files and headers. +1. Install OpenSSL binaries, at least the library files and headers. -Also you need to install [git](https://git-scm.com/download/win) to pull the source code from the repository. +1. Install [Git](https://git-scm.com/download/win) to pull the source code from the repository. -```powershell -PS> wget -o git.exe https://github.com/git-for-windows/git/releases/download/v2.28.0.windows.1/Git-2.28.0-64-bit.exe -PS> start git.exe -``` + ```text + PS> wget -o git.exe https://github.com/git-for-windows/git/releases/download/v2.28.0.windows.1/Git-2.28.0-64-bit.exe + PS> start git.exe + ``` ### Compilation -Open the start menu on Windows and type "Command Prompt for VS". From the result list select the one that corresponds to your target system ( x86 or x64). - -> **Note:** Check that the installed OpenSSL library files match the selected target. You can check the library files by using the **dumpbin** command with the **/headers** option . +1. Open the **Start menu** on Windows and type `command Prompt for VS`. From the result + list, select the one that corresponds to your target system ( `x86` or `x64`). +1. Verify the installed OpenSSL library files match the selected target. You can + examine the library files by using the `dumpbin` command with the `/headers` + option . -Clone the source code of Fluent Bit. +1. Clone the source code of Fluent Bit. -```powershell -% git clone https://github.com/fluent/fluent-bit -% cd fluent-bit/build -``` + ```text + % git clone https://github.com/fluent/fluent-bit + % cd fluent-bit/build + ``` -Compile the source code. +1. Compile the source code. -```powershell -% cmake .. -G "NMake Makefiles" -% cmake --build . -``` + ```text + % cmake .. -G "NMake Makefiles" + % cmake --build . + ``` Now you should be able to run Fluent Bit: -```powershell -% .\bin\debug\fluent-bit.exe -i dummy -o stdout +```text +.\bin\debug\fluent-bit.exe -i dummy -o stdout ``` ### Packaging To create a ZIP package, call `cpack` as follows: -```powershell -% cpack -G ZIP +```text +cpack -G ZIP ``` diff --git a/vale-styles/FluentBit/Spelling-exceptions.txt b/vale-styles/FluentBit/Spelling-exceptions.txt index b6338ebe1..ef3b7bcbe 100644 --- a/vale-styles/FluentBit/Spelling-exceptions.txt +++ b/vale-styles/FluentBit/Spelling-exceptions.txt @@ -1,6 +1,7 @@ accessor Alertmanager allowlist +Ansible API APIs Appname @@ -19,6 +20,7 @@ chronotf clickstreams CloudWatch CMake +cmdlet Config Coralogix coroutine