Search macros

The Splunk App for Unix and Linux includes a variety of search macros that can be used to create custom searches and notable events.

The back ticks (`) denote the start and the end of a search macro definition when used in the Splunk search language. The values (<timestamp>) following the search macro name denote the type and number of arguments used with the macro. Overloaded macros are macros with the same name, but a different number of required arguments.

To learn more about the syntax used in macros, see "Define search macros in Settings" and "macros.conf" in the core Splunk platform documentation.

Base macros

The following table lists the base search macros for the Splunk App for Unix and Linux. The app uses these macros to easily call up data that is stored in many indexes or has been tagged with many sourcetypes.

Search macro	Intended purpose	Expected data types
`os_index`	Used to retrieve events from the os index.
`cpu_sourcetype`	Returns cpu metric events that have a sourcetype of 'cpu'.	system access logs, such as ssh, Windows, or database audit.
`df_sourcetype`	Returns disk-space related events that have a sourcetype of 'df'	system audit logs, such as Active Directory or OpenLDAP.
`hardware_sourcetype`	Returns hardware related events that have a sourcetype of 'hardware'.	Special user accounts table and system access logs
`interfaces_sourcetype`	Returns network interface events that have a sourcetype of 'interfaces'.
`iostat_sourcetype`	Returns i/o statistics events that have a sourcetype of 'iostat'.
`lastlog_sourcetype`	Returns last login events that have a sourcetype of 'lastlog'.
`lsof_sourcetype`	Returns events that have a sourcetype of 'lsof' - a list of open files on the system.
`memory_sourcetype`	Returns memory-related events that have a sourcetype of 'memory'.
`netstat_sourcetype`	Returns network statistics events that have a sourcetype of 'netstat'.
`open_ports_sourcetype`	Returns events about open network ports.
`package_sourcetype`	Returns events about the installation and uninstallation of software packages on the system.
`protocol_sourcetype`	Returns network protocol-related events.
`ps_sourcetype`	Returns events about the status of running processes.
`rlog_sourcetype`	Returns remote login-related events.
`syslog_sourcetype`	Returns system log-related events.
`time_sourcetype`	Returns events generated by the 'time' command - the amount of time that processes take to complete on a system.
`top_sourcetype`	Returns events generated by the 'top' command - real-time statistics of all processes on a system.
`users_with_login_ privs_sourcetype`	Returns events concerning users who have the ability to log into the system.
`who_sourcetype	Returns 'who'-related events - information about the users currently logged in to the system.

Utilities and aliases

The Splunk App for Unix and Linux uses these macros to refer to common types of events. This makes it easier for the app to recognize certain events like error conditions.

Search macro	Intended purpose
`eval_host_group`
`group_add`	Returns all events where the event type is 'groupadd' or 'groupadd_suse'.
`group_del`	Returns all events where the event type is 'groupdel'.
`password_change`	Returns all events where the event type is 'linux-password-change'.
`password_change_failed`	Returns all events where the event type is 'linux-password-change-failed'.
`su_failed`	Returns all events where the event type is 'su_failed'.
`syslog_errors`	Returns all events whose text matches one of 'error', 'failed', 'severe,' but not 'assignment'.
`unix_errors`	Returns events where the event type is 'nix_errors'.
`user_add`	Returns events where the event type is either 'useradd' or 'useradd_suse'.
`user_del`	Returns events where the event type is 'userdel'.
`parse_disk_size(1)`	Parses the size of a disk based on a supplied disk event format.

Host node macros

Search macro	Intended purpose	Expected data types
unix_host_status	Returns a table of the current status of *nix hosts. Uses the `os_index`, `cpu_sourcetype`, and `eval_host_group` macros.	Host data, CPU statistics
unix_hosts_status(2)	Returns a table of the current status of *nix hosts, by group and category. Uses the `os_index`, `cpu_sourcetype`, and `eval_host_group` macros. Requires a category and group as arguments.	Host data, CPU statistics
unix_hosts_details(2)	Returns a table of detailed information (CPU, memory, disk, I/O stats) for a set of *nix hosts. Uses the `cpu_sourcetype`, `memory_sourcetype`, `df_sourcetype`, `iostat_sourcetype`, and `eval_host_group` macros. Requires a category and group as arguments.	Host data, CPU, memory, I/O, and disk statistics
unix_host_details	Returns a table of detailed information (CPU, memory, disk, I/O stats) for a set of *nix hosts. Uses the `cpu_sourcetype`, `memory_sourcetype`, `df_sourcetype`, `iostat_sourcetype`, and `eval_host_group` macros.	Host data, CPU, memory, I/O, and disk statistics
unix_nodes_heatmap_cpu	Generates the CPU heat map statistics. Uses the `os_index` and `cpu_sourcetype` macros.	Host data, CPU statistics
unix_nodes_heatmap_mem	Generates the memory heat map statistics. Uses the `os_index` and `memory_sourcetype` macros.	Host data, Memory statistics
unix_nodes_heatmap_disk	Generates the disk usage heat map statistics. Uses the `os_index` and `df_sourcetype` macros.	Host data, Disk statistics
unix_nodes_heatmap_io	Generates the I/O heat map statistics. Uses the `os_index` and `iostat_sourcetype` macros.	Host data, I/O statistics
unix_nodes_detail_ specs_cpu_by_host(1)	Returns detailed CPU specifications for a given host. Uses the `os_index` and `cpu_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics
unix_nodes_detail_ specs_mem_by_host(1)	Returns detailed memory specifications for a given host. Uses the `os_index` and `memory_sourcetype` macros. Requires a host as an argument.	Host data, Memory statistics
unix_nodes_detail_ specs_disk_drives_by_host(1)	Returns detailed disk specifications (number of volumes installed/available) for a given host. Uses the `os_index` and `df_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics
unix_nodes_detail_ specs_disk_cap_by_host(1)	Returns detailed overall disk capacity for a given host. Uses the `os_index` and `disk_sourcetype` macros. Requires a host as an argument.	Host data, Disk statistics
unix_nodes_detail_ status_cpu_by_host(1)	Returns detailed CPU statistics for a given host. Uses the `os_index` and `cpu_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics
unix_nodes_detail_ status_mem_by_host(1)	Returns detailed memory statistics for a given host. Uses the `os_index` and `memory_sourcetype` macros. Requires a host as an argument.	Host data, Memory statistics
unix_nodes_detail_ status_disk_by_host(1)	Returns detailed disk space statistics for a given host. Uses the `os_index` and `df_sourcetype` macros. Requires a host as an argument.	Host data, Disk statistics
unix_nodes_detail_ cpu_sparkline_by_host_1h(1)	Generates a spark line based on CPU statistics for a given host over the last hour. Uses the `os_index` and `cpu_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics
unix_nodes_detail_ mem_sparkline_by_host_1h(1)	Generates a spark line based on memory statistics for a given host over the last hour. Uses the `os_index` and `memory_sourcetype` macros. Requires a host as an argument.	Host data, memory statistics
unix_nodes_detail_ disk_sparkline_by_host_1h(1)	Generates a spark line based on disk usage statistics for a given host over the last hour. Uses the `os_index` and `df_sourcetype` macros. Requires a host as an argument.	Host data, disk statistics
unix_nodes_detail_ top_processes_by_host(1)	Generates a list of the top processes by CPU usage for a host. Uses the `os_index` macro and the "top" sourcetype. Requires a host as an argument.	Host data, CPU statistics, top sourcetype

Single host macros

Search macro	Intended purpose	Expected data types
CPU_Usage_by_Command_ for_Host(1)	Returns a time-series chart for CPU usage, by process, for a host. Uses the `os_index` and `ps_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics, 'ps' sourcetype
CPU_Usage_by_State_ for_Host(1)	Returns a time-series chart for CPU usage, by type (System, User, Nice, and IOWait), for a host. Uses the `os_index` and `cpu_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics
Stats_for_CPU_State_ by_Host(1)	Returns statistics for various CPU usage states (System, User, and Idle) for a host. Uses the `os_index` and `ps_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics
Top_CPU_Processes_ for_Host(1)	Returns a list of the top processes, based on CPU usage, for a host. Uses the `os_index` and `top_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics, 'top' sourcetype
CPU_Usage_by_User_ for_Host(1)	Returns a list of CPU usage, based on user, for a host. Uses the `os_index` and `ps_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics
Top_CPU_Users_ for_Host(1)	Returns a list of the top users, based on CPU usage, for a host. Uses the `os_index` and `top_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics, 'top' sourcetype
CPU_Sum_by_Command_ for_Host(1)	Returns a time-series chart for CPU usage, by process, for a host. Uses the `os_index` and `ps_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics, 'ps' sourcetype

Multiple host macros

Search macro	Intended purpose	Expected data types
Percent_CPU_by_Host(1)	Returns a time-series chart of CPU usage statistics, by host. Uses the `os_index` and `cpu_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics
Percent_Load_by_Host(1)	Returns a time-series chart of CPU load statistics, by host. Uses the `os_index` and `memory_sourcetype` macros. Requires a host as an argument.	Host data, Memory statistics
Top_5_CPU_Processes_ by_Host(1)	Returns a list of the top 5 processes, based on CPU usage, by host. Uses the `os_index` and `top_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics, 'top' sourcetype
Number_Threads_by_Host(1)	Returns a list of the number of active threads per host. Uses the `os_index` and `memory_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics
Number_Processes_by_Host(1)	Returns a list of the number of active processes per host. Uses the `os_index` and `memory_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics

Memory macros

Single host macros

Search macro	Intended purpose	Expected data types
Mem_Usage_for_Host(1)	Returns a time-series chart for memory usage for a host. Uses the `os_index` and `memory_sourcetype` macros. Requires a host as an argument.	Host data, memory statistics
Mem_Usage_by_Command_ for_Host(1)	Returns a time-series chart for memory usage, by process, for a host. Uses the `os_index` and `ps_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics, 'ps' sourcetype
Top_Mem_Command_ for_Host(1)	Returns a list of the top processes, based on memory usage, for a host. Uses the `os_index` and `ps_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics, 'ps' sourcetype
Top_Users_of_VM_ for_Host(1)	Returns a time-series chart of virtual memory usage, per user, for a host. Uses the `os_index` and `ps_sourcetype` macros. Requires a host as an argument.	Host data, CPU statistics, 'ps' sourcetype

Multiple host macros

Search macro	Intended purpose	Expected data types
Percent_MEM_by_Host(1)	Returns a time-series chart of memory usage statistics, by host. Uses the `os_index` and `memory_sourcetype` macros. Requires a host as an argument.	Host data, Memory statistics
Top_Mem_Processes_ by_Host(1)	Returns a list of the top processes, based on memory usage, by host. Uses the `os_index` and `ps_sourcetype` macros. Requires a host as an argument.	Host data, Memory statistics, 'ps' sourcetype
Memory_Hardware_by_Host(1)	Returns the memory specification for each host. Uses the `os_index` and `hardware_sourcetype` macros. Requires a host as an argument.	Host data, Memory and Hardware statistics
Top_Memory_Users_by_Command_ by_Host(1)	Returns a list of the top memory users, by command, for a host. Uses the `os_index` and `ps_sourcetype` macros. Requires a host as an argument.	Host data, Memory statistics, 'ps' sourcetype

Network macros

Search macro	Intended purpose	Expected data types
Thruput_by_Interface_by_Host(1)	Returns a time-series chart of network throughput, per interface, per host. Uses the `os_index` and `interfaces_sourcetype` macros. Requires a host as an argument. Requires a host as an argument.	Host data, Network statistics
Top_Inet_Addresses_by_Host(1)	Returns a list of the top IP addresses that a host has attempted a network operation on. Uses the `os_index` and `interfaces_sourcetype` host. Requires a host as an argument.	Host data, Network statistics
Open_Ports_by_Host(1)	Returns a list of open TCP ports on a system (with friendly names for most popular ports). Uses the `os_index` and `open_ports_sourcetype` macros. Requires a host as an argument.	Host data, Network statistics
Addresses_by_Host(1)	Returns a list of the number of inbound network connections, by IP address, to a host. Uses the `os_index` and `netstat_sourcetype` macros. Requires a host as an argument.	Host data, Network statistics, 'netstat' sourcetype
Sockets_by_State_by_Host(1)	Returns a time-series chart of the number of open network sockets, by socket state, for a host. Uses the `os_index` and `netstat_sourcetype` macros. Requires a host as an argument.	Host data, Network statistics, 'netstat' sourcetype
Frequently_Open_Ports_ by_Host(1)	Returns a list of the most frequently opened TCP ports, by port number, for a host. Uses the `os_index` and `open_ports_sourcetype` ports. Requires a host as an argument.	Host data, Network statistics

Disk macros

Search macro	Intended purpose	Expected data types
Disk_Used_Pct_by_Host(1)	Returns a time-series chart of the percentages of disk used per host. Uses the `os_index` and `df_sourcetype` macros. Requires a host as an argument.	Host data, Disk statistics
Latest_Disk_Used_by_Host(1)	Returns a list of the most up-to-date disk usage per host. Uses the `os_index` and `df_sourcetype` macros. Requires a host as an argument.	Host data, Disk statistics
Max_Disk_Used_by_Host(1)	Returns a list of disk usage percentage, per host, sorted in descending order. Uses the `os_index` and `df_sourcetype` macros. Requires a host as an argument.	Host data, Disk statistics
Open_Files_by_Command_ and_Host(1)	Returns a time-series chart of the number of open files, per command, for a host. Uses the `os_index` and `lsof_sourcetype` macros. Requires a host as an argument.	Host data, Disk statistics
Open_Files_by_Type_and_Host(1)	Returns a time-series chart of the number of open files, by file type, for a host. Uses the `os_index` and `lsof_sourcetype` macros. Requires a host as an argument.	Host data, Disk statistics
Open_Files_by_User_and_Host(1)	Returns a time-series chart of the number of open files, by user, for a host. Uses the `os_index` and `lsof_sourcetype` macros. Requires a host as an argument.	Host data, Disk statistics

User macros

Search macro	Intended purpose	Expected data types
User_Sessions_by_Host(1)	Returns a list of active user sessions on a host. Uses the `os_index` and `who_sourcetype` macros. Requires a host as an argument.	Host data, Login statistics
Failed_Logins_by_Host(1)	Returns a list of hosts that have had failed logins. Uses the `os_index` macro and the "failed_login" event type. Requires a host as an argument.	Host data, Login statistics
Users_with_Login_Privs_ by_Host(1)	Returns a list of hosts where users have login privileges. Uses the `os_index` and `users_with_login_privs_sourcetype` macros. Requires a host as an argument.	Host data, Login statistics