The documentation of the syslog-ng Store Box(SSB) RPC API is available online from the following URL: https://<ip-address-of-SSB>/api/4/documentation. This documentation contains the detailed description of public calls, with examples. For a quickstart guide, see the RPC API Quickstart Guide.
Preface
Introduction
The concepts of SSB
The philosophy of SSB
Collecting logs with SSB
Managing incoming and outgoing messages with flow-control
Receiving logs from a secure channel
Advanced Log Transfer Protocol
Network interfaces
High Availability support in SSB
Firmware in SSB
Versions and releases of SSB
Licensing model and modes of operation
Licensing benefits
License types
Licensing examples
The structure of a log message
The Welcome Wizard and the first login
The initial connection to SSB
Basic settings
Creating an alias IP address (Microsoft Windows)
Creating an alias IP address (Linux)
Modifying the IP address of SSB
Configuring SSB with the Welcome Wizard
Supported web browsers
The structure of the web interface
Network settings
User management and access control
Configuring the external interface
Configuring the management interface
Configuring the routing table
Date and time configuration
SNMP and email alerts
Configuring email alerts
Configuring SNMP alerts
Querying SSB status information using agents
View node ID and community
Configuring system monitoring on SSB
Configuring SNMP agent settings
Health monitoring
Preventing disk space fill up
Configuring message rate alerting
System related traps
Alerts related to syslog-ng PE
Data and configuration backups
Creating a backup policy using Rsync over SSH
Creating a backup policy using SMB/CIFS
Creating a backup policy using NFS
Creating configuration backups
Creating data backups
Encrypting configuration backups with GPG
Archiving and cleanup
Managing SSB users locally
Setting password policies for local users
Managing local usergroups
Managing SSB users from an LDAP database
Authenticating users to a RADIUS server
Authenticating users via OpenID Connect
Managing user rights and usergroups
Managing SSB
Assigning privileges to usergroups for the SSB web interface
Modifying group privileges
Finding specific usergroups
How to use usergroups
Built-in usergroups of SSB
Listing and searching configuration changes
Controlling SSB: restart, shutdown
Managing a high availability SSB cluster
Configuring message sources
Adjusting the synchronization speed
Asynchronous data replication
Redundant heartbeat interfaces
Next-hop router monitoring
Upgrading SSB
Upgrade checklist
Upgrading SSB
Upgrading an SSB cluster
Troubleshooting
Updating the SSB license
Monthly license host usage report
Exporting the configuration of SSB
Importing the configuration of SSB
Accessing the SSB console
Using the console menu of SSB
Enabling SSH access to the SSB host
Changing the root password of SSB
Changing the GRUB password of SSB
Sealed mode
Out-of-band management of SSB
Managing the certificates used on SSB
Generating certificates for SSB
Uploading external certificates to SSB
Generating TSA certificate with Windows Certificate Authority on Windows Server 2008
Generating TSA certificate with Windows Certificate Authority on Windows Server 2012
Creating hostlist policies
Default message sources in SSB
Creating new message sources in SSB
Storing messages on SSB
Configuring your own, customized Syslog type message source
Receiving SNMP messages
Configuring the Listening address and Listening port for your Syslog type message source
Configuring the Transport options for your Syslog type message source
Configuring the Hostname and timestamp-related settings for your Syslog type message source
Configuring the Monitoring settings for your Syslog type message source
Customizing encoding for your Syslog type message source
Configuring your own, customized SQL type message source
Setting up and testing the SQL database connection of your SQL type message source
Customizing fetching messages when using your SQL type message source
Customizing the fetch query for your SQL type message source
Customizing the fetch history settings for your SQL type message source
Configuring the fetching frequency settings for your SQL type message source
Configuring the Monitoring settings for your SQL type message source
Using logstores
Creating text logspaces
Managing logspaces
Forwarding messages from SSB
Managing logspaces - Archive and backup logspaces
Assigning the SSB logspace of your choice to a custom cloud service provider data disk
Creating filtered logspaces
Creating remote logspaces
Creating multiple logspaces
Accessing log files across the network
Managing custom cloud service provider data disks for your logspaces in SSB
Possible use cases and scenarios for using custom cloud service provider data disks with SSB
Adding a new custom cloud service provider data disk to your SSB configuration
Adding a new custom cloud service provider data disk on the cloud service provider side
Removing a custom cloud service provider data disk from your SSB configuration
Increasing the size of a custom cloud service provider data disk that you use in your SSB configuration
Adding a new Microsoft Azure-managed disk as a custom cloud service provider data disk on the Microsoft Azure Portal side
Adding an additional disk in VMware ESXi as a custom cloud service provider data disk on the vSphere Client side
Adding a new custom cloud service provider data disk to your SSB configuration on the SSB side
Forwarding log messages to SQL databases
SQL templates in SSB
Forwarding log messages to remote servers
Forwarding log messages to the Microsoft Azure Sentinel cloud
Log paths: routing and processing messages
Prerequisites
Limitations
Configuring the Azure Sentinel destination: adding a new Azure Sentinel destination
Forwarding log messages to Google Pub/Sub
Prerequisites
Limitations
Configuring the Google Pub/Sub destination: adding a new Google Pub/Sub destination
Forwarding log messages to Splunk
Prerequisites
Limitations
Transport settings for the Splunk destination
HTTP connection settings
HTTPS connection settings
JSON message body
Performance-related settings
Forwarding log messages to HDFS destinations
Default logpaths in SSB
Creating new log paths
Filtering messages
Replace message parts or create new macros with rewrite rules
Find and replace the text of the log message
Parsing sudo log messages
Parsing key-value pairs
Configuring syslog-ng options
General syslog-ng settings
Time stamping configuration on SSB
Using name resolution on SSB
Setting the certificates used in TLS-encrypted log transport
Searching log messages
Using the search interface
Searching the internal messages of SSB
Customizing columns of the log message search interface
Metadata collected about log messages
Using complex search queries
Browsing encrypted logspaces
Using persistent decryption keys
Using session-only decryption keys
Assigning decryption keys to a logstore
Creating custom statistics from log data
Creating content-based alerts
Setting up alerts on the search interface
Setting up alerts on the Search > Content-Based Alerts page
Format of alert messages
Additional tools
Using the internal search interfaces
Changelogs of SSB
Configuration changes of syslog-ng peers
Log message alerts
Notifications on archiving and backups
Status history and statistics
Reports
Classifying messages with pattern databases
The structure of the pattern database
How pattern matching works
Searching for rulesets
Creating new rulesets and rules
Exporting databases and rulesets
Importing pattern databases
Using pattern parsers
Using parser results in filters and templates
Using the values of pattern parsers in filters and templates
The SSB RPC API
Monitoring SSB
Monitoring SSB's disk
Monitoring SSB's memory
Monitoring SSB's CPU
Monitoring SSB's I/O
Monitoring SSB statistics
Monitoring the HA cluster
Monitoring hardware RAID
Monitoring software RAID
Monitoring web server, root CA and TSA certificates
Troubleshooting SSB
Locating the SSB appliance in the server room
Network troubleshooting
Gathering data about system problems
Viewing logs on SSB
Collecting logs and system information for error reporting
Troubleshooting an SSB cluster
Security checklist for configuring SSB
Glossary
Understanding SSB cluster statuses
Recovering SSB if both nodes broke down
Recovering from a split brain situation
Replacing a node in an SSB HA cluster
Resolving an IP conflict between cluster nodes
Restoring SSB configuration and data
Configuring the IPMI interface from the BIOS after losing IPMI password
Accessing and using the SSB boot loader menu and console
Incomplete TSA response received
Correct Alerting & Monitoring and Management group privilege mismatch
Documentation of the RPC API
Monitoring SSB
Monitoring SSB
This section describes monitoring syslog-ng Store Box(SSB).
If you intend to monitor SSB, the general rules of monitoring an Ubuntu system apply.
Depending on your monitoring tool, check out the available SNMP templates related to your system, and use those to monitor the general parts of SSB.
Topics:
|
|
Caution:
Do not install any monitoring agent on the SSB appliance. Any alteration to the system is unsupported. |
For details on receiving email alerts or SNMP traps on health- and system-related issues, see Configuring system monitoring on SSB.
For details on SNMP communities, see View node ID and community.
Monitoring SSB's disk
| SNMP object: | HOST-RESOURCES-MIB::hrStorageTable |
|
Community (v2c) / Context (v3) |
Data and system |
This section describes monitoring syslog-ng Store Box(SSB)'s disk usage. Disk usage is measured per mountpoint (that is, partition).
Data partition
| Mountpoint | /mnt/firmware |
| Partition | data partition |
| Community |
<community-of-extended-node> (Basic Settings > Monitoring > SNMP agent settings > Community) |
| Context | "" (empty string) |
Free disk space that can be acquired by your main production system (for example, logspaces).
To make sure that you have the free disk space you are comfortable with, monitor the free disk space. This partition can fill up with for example the following:
-
received logs
-
generated reports
-
collected statistics
-
core dumps
If you cannot keep your free disk space in your comfortable interval (with scheduled cleanups) you probably need to purchase more SSB appliances. For assistance, contact our Support Team.
NOTE: If you have configured Basic Settings > Management > Disk space fill up prevention, be aware that SSB will stop receiving log after reaching the configured threshold. By default, clients are disconnected when disks are 90 percent full. For details, see Preventing disk space fill up.
| For which systems and configurations is it applicable? | Applicable for all configurations and systems. |
| Value change frequency | The file system's available space is continuously decreasing, depending on logspaces, reports, statistics, and core files. |
| Related issues and issue indicators |
The monitored values may indicate that the used storage space has reached the level configured under Basic Settings > Management > Disk space fill up prevention. In this case, archiving starts (if archiving is configured), and incoming logs are rejected. NOTE: If the disk fill up prevention level is reached too often and too soon, it indicates a serious issue. |
|
|
Caution:
Hazard of data loss If the used storage space of the file system under /mnt/firmware exceeds the allowed rate configured under Basic Settings > Management > Disk space fill up prevention, SSB will stop receiving log messages. To avoid data loss, archive your logs or store them in some other way (for example, forward your log messages to different logstores). Alternatively, reconsider your configuration settings, upgrading the capacity of your SSB appliance, or purchasing more SSB appliances. |
Solution:
-
Consider upgrading the capacity of your SSB appliance or purchasing more SSB appliances (for more information, see Hardware specifications or contact our Sales Team).
- Reconsider your configuration settings.
- Archive your logs from your logspaces to clean up logstores on your SSB appliance.
System partition
| Mountpoint | /initrd/mnt |
| Partition | system partition (if SSB is in HA mode, the system firmware partition of both nodes) |
| Community | <id-of-the-node> |
| Context | <id-of-the-node> |
The space on this mountpoint is required only by the system. Generally, this is independent from how you use SSB. The only important thing here to have some free space on the mountpoint.
Make sure that you have some free space on this mountpoint. As a recommended threshold, set a trigger to 80% in your monitoring system. If there is only about 20% free space left on this mountpoint, contact our Support Team.
NOTE: Monitoring the size of specific logspaces is not possible this way. If you are interested in the size of a specific logspace, you can configure a size limit alert for that logspace on the SSB web interface. For details on configuring a disk size alert for a specific logspace, see Creating logstores.
| For which systems and configurations is it applicable? | Applicable for all configurations and systems. |
| Value change frequency | The available storage space is not supposed to decrease significantly. |
| Related issues and issue indicators | The monitored values may indicate that the system is out of storage space, or that the available storage space is running very low. |
|
|
Caution:
Hazard of data loss If the used storage space of the file system under /mnt/firmware exceeds the allowed rate configured under Basic Settings > Management > Disk space fill up prevention, SSB will stop receiving log messages. To avoid data loss, archive your logs or store them in some other way (for example, forward your log messages to different logstores). Alternatively, reconsider your configuration settings, upgrading the capacity of your SSB appliance, or purchasing more SSB appliances. |
Solution:
If you encounter an issue related to the file system under /initrd/mnt, contact our Support Team.
Monitoring SSB's memory
Swap usage
| SNMP object: |
|
|
Community (v2c) / Context (v3) |
Data and system |
The syslog-ng Store Box(SSB) appliance is using swap (except on Azure) as part of its normal operation.
You can receive swap usage alerts by configuring an alert on Basic Settings > Alerting. For details, see Configuring system monitoring on SSB.
| For which systems and configurations is it applicable? | Applicable for all configurations and systems. |
| Value change frequency | Its value is continuously changing. |
| Related issues and issue indicators | If the computed returned value is close to 0, memory usage is too high. |
Solution:
- Decrease load.
-
Purchase a new SSB appliance.
Memory usage
| SNMP object: |
|
|
Community (v2c) / Context (v3) |
Data and system |
If SSB's memory and swap usage are both above 90%, fine-tune your configuration or purchase more SSB appliances to balance the load. For assistance, contact our Support Team.
| For which systems and configurations is it applicable? | Applicable for all configurations and systems. |
| Value change frequency | Its value is continuously changing. |
| Related issues and issue indicators | If the computed returned value is close to 0, memory usage is too high. |
Solution:
- Decrease load.
- Purchase a new SSB appliance.