SAF Beat for Windows
SAF Beat can work with any version of ElasticBeat, but if you plan to send these examples to OpenSearch, then the ElasticBeat version should be 7.12.1 (or 7.10.2 is a more stable version). If you plan to use Logstash, then the ElasticBeat version does not matter. Check on the official website.
Symbols
$SB_HOME- SAF Beat installation home directory: `C:\Program Files\SAF Beat
Installation using an MSI file
Run the SAF Beat MSI file at a certain bit rate:
- If Windows is x32, you need to run
SAFBeat-windows-x86-version.msi. - If Windows is x64, you need to run
SAFBeat-windows-x64-version.msi.
Select the SAF Beat installation path (standard installation path: C:\Program Files\SAF Beat):
Setting up connection to SAF Beat Manager
At this stage, you need to configure the following parameters of the SAF Beat configuration file:
| Parameter | Description | Default Value |
|---|---|---|
| Manager | Setting up to connect to SAF Beat Manager. You must specify the IP address or DNS name of the machine where SAF Beat Manager is installed, and the connection port (host and port must be separated by the symbol :). | localhost:7767 |
| Heartbeat | Configuring the SAF Beat connection parts to the SAF Beat Manager. |
Setting up an SSL connection
It is recommended to use a secure connection.
Enter the paths to the certificates to securely connect SAF Beat to SAF Beat Manager:
By default, a secure connection with certificate verification is enabled. To do this, you must specify the path to the CA certificate and the certificate and key of the SAF Beat itself. It is recommended to generate certificates with the following parameters:
keyUsage = critical, digitalSignature, keyEnciphermentextendedKeyUsage = serverAuth, clientAuthSubject Alternative Name- specify all possible IP and domain names of the server where the agent is installed
To generate a certificate, you can use the utility provided in the installer $SM_INSTALLER/utils/ssl-tls-gen/gencerts.sh . In order to disable certificate verification, you need to disable the Enable verification checkbox. To generate self-signed certificates, check the box Generate self-signed certificate. In this case, the CA certificate will not be taken into account and will be ignored. In order not to use a secure connection, uncheck the Enable SSL box.
Log file rotation
At this step, the parameters responsible for logging are configured:
- Rotation time - the frequency of rotation of the logging file. The default is 24 hours.
- Max age - the lifetime of the logging file. The default is 1 week.
- Logs path - the directory for saving logs. By default:
C:\Program Files\SAF Beat\logs\.
Additional SAF Beat Settings
At this step, you can configure the following actions:
- Delete GUID SAF Beat - this action must be performed only when updating SAF Beat. If you perform this action during installation, nothing will happen. Delete the
guid.ymlfile (a file containing a unique SAF Beat identifier). - Set ExecutionPolicy on RemoteSigned - this action must be performed when you are going to configure the collection using Powershell scripts. The policy for the user will change to
RemoteSigned. - The salt in the SAF Beat GUID - this action is recommended to avoid duplicates of the SAF Beat GUID installed on different machines that have been copied. Add salt when generating the SAF Beat GUID (the
guid_saltparameter in theconfig.yamlconfiguration file).
After the SAF Beat is configured correctly, run the installation - Install, and when prompted "Account Control - Allow this application from an unknown publisher to make changes on your device", click Yes.
After SAF Beat is installed on your computer, the SAF Beat service will start and the agent will connect to SAF Beat Manager.
Quiet installation
To install Smart Bat on Windows using a silent MSI installation, you need to open a command prompt or powershell as an administrator to execute commands.
cd 'C:\<path to SAF Beat-windows-x64-version.msi>'
msiexec /i SAF Beat-x64.msi /qn
When installing SAF Beat, using a silent MSI installation, you can specify the keys for configuring the MSI. If you do not specify a key, the default value will be applied.
| Parameter | Description | The default value |
|---|---|---|
GUID_SALT | Adding salt when generating a GUID. Required if you are using virtual machines copied from one. By default, it is empty. It is possible to add <IP> <MAC>, the values are substituted automatically from the current server. | |
APPDIR | SAF Beat installation path | C:\Program Files\SAF Beat |
SBMANAGER | Host (IP address or DNS name) and port of SAF Beat Manager. | localhost:7767 |
HEARTBEAT_MIN | Minimum SAF Beat connection frequency. | 1m0s (1 minute) |
HEARTBEAT_MULTIPLIER | The multiplier of the minimum connection frequency. | 2 |
HEARTBEAT_MAX | The maximum connection frequency of the SAF Beat. | 1h0m0s (1 hour) |
ROTATION_INTERVAL | The frequency of rotation of the logging file. | 24h (24 hours) |
ROTATION_AGE | The lifetime of the logging file. | 168h (1 week) |
ROTATION_LOG_LEVEL | Logging mode (info/debug/trace) SAF Beat. | info |
ROTATION_LOG_PATH | Directory for saving logs. | C:\Program Files\SAFBeat\logs\ |
SSL_VERIFY | Secure connection to SAF Beat Manager. | false |
SSL_ENABLE | Protocol for connecting to SAF Beat Manager, where the https protocol is used when set to true, and the http protocol is used when set to false. | true |
SSL_CERT_CA | The absolute/relative path to the certificate CA. | |
SSL_CERT_NODE | Absolute/relative path where the node certificate is generated. | C:/Program Files/SAFBeat/cert/node-cert.pem |
SSL_KEY_NODE | The absolute/relative path where the node key is generated. | C:/Program Files/SAFBeat/cert/node-key.pem |
REMOVE_GUID | Delete the guid.yml file. | false |
SET_EXECUTION_POLICY | Change the permission policy for running PowerShell scripts. | false |
It is not necessary to specify all the parameters, it is enough to specify only which ones need to be changed.
An example of using keys when installing MSI silently on Windows x64 using powershell:
msiexec /i SAFBeat-windows-x64-version.msi /qn APPDIR=`"C:\Program Files\SAFBeat`" GUID_SALT="<IP>_<MAC>" SBMANAGER="localhost:7767" HEARTBEAT_MIN="1m0s" HEARTBEAT_MULTIPLIER=2 HEARTBEAT_MAX="1h0m0s" ROTATION_INTERVAL="24h" ROTATION_AGE="168h" ROTATION_LOG_LEVEL=info ROTATION_LOG_PATH=`"C:\Program Files\SAFBeat\logs`" SSL_VERIFY=true SSL_ENABLE=true SSL_CERT_CA=`"C:\Program Files\SAFBeat\cert\ca-cert.pem`" SSL_CERT_NODE=`"C:\Program Files\SAFBeat\cert\cert.pem`" SSL_KEY_NODE=`"C:\Program Files\SAFBeat\cert\key.pem`" REMOVE_GUID=false SET_EXECUTION_POLICY=false
When using a space character in the value of one of the parameters, it is necessary to specify the value in double quotes with escaping using the ` character. For example:
APPDIR=`"C:\Program Files\SAFBeat`"
An example of using the keys when quietly installing MSI on Windows x64 using the command line:
msiexec /i SAFBeat-windows-x64.msi /qn APPDIR="C:\Program Files\SAFBeat\" GUID_SALT="<IP>_<MAC>" SBMANAGER="localhost:7767" HEARTBEAT_MIN="1m0s" HEARTBEAT_MULTIPLIER=2 HEARTBEAT_MAX="1h0m0s" ROTATION_INTERVAL="24h" ROTATION_AGE="168h" ROTATION_LOG_LEVEL=info ROTATION_LOG_PATH="C:\Program Files\SAFBeat\logs\" SSL_VERIFY=false SSL_ENABLE=true SSL_CERT_CA="C:\Program Files\SAFBeat\cert\ca-cert.pem" SSL_CERT_NODE="C:\Program Files\SAFBeat\cert\cert.pem" SSL_KEY_NODE="C:\Program Files\SAFBeat\cert\key.pem" REMOVE_GUID=false SET_EXECUTION_POLICY=false
Additional SAF Beat Settings
Replacing certificates
To replace the SAF Beat certificates and private key, follow these steps:
- Stop the SAF Beat service.
- In the
${SB_HOME}/cert/directory, delete all existing certificates and private keys. - Transfer the existing CC certificate, certificate and SAF Beat private key to the same directory
${SB_HOME}/cert/. - Edit, if necessary, the configuration file
${SB_HOME}/config/config.yaml:ssl.cert_ca- specify the name of the CA's x509 certificate.ssl.node_certis the file name of the x509 SAF Beat certificate.ssl.node_keyis the file name of the SAF Beat private key.ssl.enable: true- enable SSL/TLS.ssl.verify: true- enable certificate validation.
- Launch the SAF Beat service.
User Change
In order to change the user under which SAF Beat works, you need to do the following:
- Turn off the SAF Beat service.
- Change the owner of the directory
${SB_HOME}and all attached files and directories. - Add permission to read all necessary files to the new SAF Beat user.
- Launch the "Local Security Policy", open "Security Settings -> Local Policies -> Assigning user rights -> Logging in as a service" - add a new SAF Beat user
- Launch the SAF Beat service.
Changing the GUID
The GUID is formed based on the UUID of the disk that is mounted on the root of the file system. At startup, SAF Beat calculates the GUID and in the absence of the file ${SB_HOME}/config/guid.yml stores the received value in it. With an existing file, it compares the received value and the value in the file and writes the result in a log file.
If the virtual servers were cloned, then a situation may arise in which the UUIDs will be the same, for this you should add salt when generating the GUID. In the configuration file ${SB_HOME}/config/config.yaml, you need to add the parameter guid_salt. Currently, you can add 2 tokens, which are calculated for each server:
<IP>- substitutes the IP address from which themanager.hostserver is accessed or the value from theagent.ipparameter is taken (must be real, otherwise it will be selected randomly)<MAC>- substitutes the MAC of a network device that has the IP address obtained above
To change the SAF Beat GUID, follow these steps:
- Stop the SAF Beat service.
- Delete the file
${SB_HOME}/config/guid.yml. - Edit the configuration file
${SB_HOME}/config/config.yamland make changes to the parameterguid_salt- specify the necessary "salt", it is recommended to use the value from the tokens<IP> <MAC>. - Launch the SAF Beat service.
Description of the configuration file
The configuration file ${SB_HOME}/config/config.yaml consists of the following parameters:
| Parameter | Description | Default value |
|---|---|---|
guid_salt | Salt when generating GUID for SAF Beat. | <IP> <MAC> |
heartbeat.min_condition | The minimum connection frequency of SAF Beat. | 1m0s (1 minute) |
heartbeat.min_condition | The minimum connection frequency of SAF Beat. | 1m0s (1 minute) |
heartbeat.multiplier | Multiplier of the minimum connection frequency. | 2 |
heartbeat.max_condition | The maximum connection frequency. | 1h0m0s (1 hour) |
manager.host | Host (IP address or DNS name) SAF Beat Manager. | localhost |
manager.port | Port of SAF Beat Manager. | 7767 |
agent.ip | The IP address of the agent. It is used in the case of multiple network interfaces to select the agent`s IP address to be sent to the SAF Beat Manager. The specified IP address must be assigned to one of the host's network interfaces, otherwise the parameter will be filled with the default value. An optional parameter. | The IP address of the network interface of the host through which the request to the SAF Beat Manager passes. |
agent.tags | An array of agent labels. On the SAF Beat Manager side, it is not used yet. An optional parameter. | [] |
agent.send_addrs | Enabling sending information about the host's network interfaces. If the value is true, then an array of addrs objects will be sent to SAF Beat Manager, where each object consists of three fields inter - the interface name, hwaddr - the physical address of the interface, ipv4 - the ip address assigned to the interface. On the SAF Beat Manager side, it is not used yet. An optional parameter. | true |
rotation.rotation_time | The frequency of rotation of the logging file. | 24h (24 hours) |
rotation.max_age | Lifetime of the logging file. | 168h (1 week) |
rotation.max_size | Limit the size of the logging file. | 10485760 (10 MB) |
rotation.log_level | Logging level. It can take the values trace, debug, info, warn, error, fatal. It is recommended to use the debug level for debugging. | info |
rotation.log_path | Directory for saving logs. | ./logs |
ssl.verify | Checking ssl certificates when securely connected to SAF Beat Manager. | false |
ssl.enable | Secure connection to SAF Beat Manager. | true |
ssl.cert_ca | Path to the CA of the certificate. | ./cert/ca-cert.pem |
ssl.node_cert | Path to generate the node certificate. | ./cert/node-cert.pem |
ssl.node_key | Path to generate the node key. | ./cert/node-key.pem |