Splunk® App for Unix and Linux (Legacy)

Install and Use the Splunk App for Unix and Linux

Acrobat logo Download manual as PDF


On March 13, 2022, the Splunk App for Unix and Linux will reach its end of life. After this date, Splunk will no longer maintain or develop this product. The functionality in this app has migrated to a content pack in Data Integrations. Learn about the Content Pack for Unix Dashboards and Reports.The Splunk Add-on for Unix and Linux remains supported.
This documentation does not apply to the most recent version of Splunk® App for Unix and Linux (Legacy). For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

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
Last modified on 17 November, 2016
PREVIOUS
Saved searches
  NEXT
Release notes

This documentation applies to the following versions of Splunk® App for Unix and Linux (Legacy): 5.2.2


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters