The documentation for the lookup function on Splunk’s website proved to be immensely confusing and did me no favours at all. A few hours of trial and error later, I figured it out. This example will use a csv file that translates IP Protocol to Names intended for use with an SRX app I’m working on.
Procedure
Create a csv file with headers. Bear in mind that the key you want to look up against (the first field) MUST be an existing field name in Splunk. At the time I had a field extraction called srx_protocol_id so the first field is labelled as such. Be careful of calling your lookups and primary keys by the same name, otherwise it gets confusing.
ip-protocol-numbers.csv (truncated)
srx_protocol_id,protocol_name
0,HOPOPT
1,ICMP
2,IGMP
3,GGP
4,IPv4
5,ST
6,TCP
7,CBT
8,EGP
9,IGP
10,BBN-RCC-MON
11,NVP-II
12,PUP
13,ARGUS
14,EMCON
15,XNET
16,CHAOS
17,UDP
First of all, select App > Your App from the top menu.
Go to Manager > Lookups > Lookup Table Files > New
Select the relevant App, select the file with [ Choose File ] and give the same filename, eg: ip-protocol-numbers.csv
Once done, your path may be an admin path, so edit the permissions of the file you uploaded to be “This app only” and select Read for Everyone and write for admin and power. The path should change to
home/splunk/opt/splunk/etc/apps/[APPNAME]/lookups/ip-protocol-numbers.csv
Create a protocol definition.
Destination App: Your App
Name: ip-protocols
Type: File based
Lookup file: ip-protocol-numbers.csv
[X] Advanced options
Minimum matches: 1
Maximum matches: 1
Default matches: NA
The above settings are chosen because we only expect 1 name per protocol ID, and if it doesn’t match, we want NA to be returned. If the Lookup file you want isn’t showing up and your permissions are OK, you may need to restart splunk.
Searching
Now I can look up the protocol name in the following search:
RT_FLOW_SESSION | dedup 1 host,srx_sess_id keepempty=true | top limit=0 srx_protocol_id | lookup ip-protocols srx_protocol_id | fields - srx_protocol_id percent | rename protocol_name AS "Protocol"
By default, a lookup will return all fields that match the primary key. If you have several fields you can modify your search with the following to restrict the fields you want output.
lookup [lookup-name] [search field name] OUTPUT [field name in csv file]