This document last updated: 07/31/07 03:07pm

Print Installation Manual

Before You Start

System Requirements

Host Operating System

Client Operating System / Browser

Server Hardware

64-bit architectures are not yet supported natively. They will be soon. In the meantime, for Linux, you can use the 32-bit compatibility libraries.

File System

Note: Running Splunk on a filesystem not listed will result in a startup function named locktest not allowing Splunk to start

Minimum

Recommended

What Gets Installed

Who'll be able to Splunk your Data

Step by Step

Installation in 3 Easy Steps

Step 0: Read this first

Updating a previous version?

Troubleshooting an Installation

We've collected a list of known Installation Errors and their fixes. If you encounter any errors or warnings during the process - or anything that seems wrong - please check there first.

Step 1: Unpack the software

Each platform-specific installer comes in both a package form and a tarball. The Linux build comes in three forms: RPM, deb and tarball. The FreeBSD installer and tarball are both .tgz files. 5.4-intel is the installer, i386 is the tarball.

Follow the instructions for your specific package or tarball.

Tarball

RPM

# rpm -i splunk-2.1-0.i386.rpm

# rpm -i --force --prefix=/opt/splunk2.1/splunk splunk-2.1-0.i386.rpm

deb

# dpkg -i splunk-2.1-linux-2.6-intel.deb

The Splunk deb package currently cannot be installed in a directory other than its default, /opt/splunk.

# dpkg -r splunk

# dpkg -P splunk

# dpkg --status splunk

# dpkg --list

FreeBSD

# pkg_add splunk-2.1-freebsd-5.4-intel.tgz

# pkg_add -v -p /usr/splunk splunk-2.1-freebsd-5.4-intel.tgz

# pkg_delete splunk

# pkg_delete -p /usr/splunk splunk

# pkg_info -L splunk

# pkg_info

MacOS

Double-click on splunk.pkg

When the installer gets to the Select Destination dialog, click Choose... to select a directory other than /Applications

# installer -pkg splunk.pkg

# installer -pkg splunk.pkg -target /Volumes/LaCie\ Disk

-target specifies a target volume, such as another disk, where Splunk will be installed in /Applications/splunk .
To install into a directory other than /Applications/splunk on any volume, use the graphical installer as described above.

Solaris

# pkgadd splunk.pkg

# pkgadd -d /user/splunk/splunk.pkg

# pkgrm splunk

# pkginfo -l splunk

# pkginfo

Step 2: Install your license

All Splunk Servers have a license in the subdirectory ./etc/splunk.license . The free server has a built-in free license. A license for Splunk Professional enables higher volume indexing and Splunk Professional features.

Note: This is for splunk 2.2.3, for the beta and latest release, see 3.0 instructions.

<license>
    <user>Billy_Name</user>
    <expiration-date>2008-05-11 14:52:31</expiration-date>
    <creation-date>2007-04-11 14:52:31</creation-date>
    <bytelimit>5000 MB</bytelimit>
    <version>Splunk Professional Annual</version>
    <type>trial</type>
    <licenseKey>nDwuRTC4rmUNzUtECtae3s5ukOAxqY7xSmT9DJbrO4eSttXA4bj37YfB8l+2VhZkCeQF3Wrb+7wTnykKP3CqlPkx0bwluj62gZWK3b9t9THeUBz5UE
8e3NiP1eqPu9wtofxubifxL4zkwzaxPuwzg/7YKsbkgWai8QBCJaKvUqIdi7IZ1l3JAK2qhqmsnxaOixEU3kxerB5w90AfpdiaSKD5v2orQZPQBWT+4tVZe8gQupeLi4t88Mi
SyqARgagE2Z6YV/D5/1HMlBFB4rrh16M8OGDeYy73m2uocCXhYq9sFJKN2zygTOyDuE1769NaJ4CWGRWlsk31S6R3HjUOVg==</licenseKey>
    <productName>splunk</productName>
</license>

# cp -p splunk.license /opt/splunk/etc/

If you are installing a Splunk Professional license (including a free 30 day evaluation license) for the first time, you will need to log in with the default administrator account: username "admin" and password "changeme".

Step 3: Start Splunking!

A. Start the server

# /opt/splunk/bin/splunk start
(or whatever path you installed)

The first time you run a new installation, you will be prompted with a license agreement.

B. Load the Splunk GUI in your browser

http://mysplunkhost:8000
(or whatever host and port you installed)

(Use username "admin" and password "changeme" to login to your new Splunk Professional installation for the first time.)

C. Set up one or more data inputs

The first time you browse a new installation, you will see a Guided Setup tool that helps you set up data inputs, licenses, and Splunk-2-Splunk configuration. Alternately, you can configure data inputs from the command line. Below is a typical example.

# /opt/splunk/bin/splunk add tail /var/log

Your Splunk Server should show indexed data on its home page immediately after you add a data input. As soon as you see a number greater than "0 events" listed on the server's home page, you're ready to start Splunking!

Updating the license

# cp -p splunk.license /opt/splunk/etc/

When the correct license is in place, start or restart the Splunk Server.
# /opt/splunk/bin/splunk restart

Help

Built-in

The Splunk Server comes with three help resources built into its interface and served locally.

Splunk's Web interface has a built-in window that will walk you through basic setup of your data inputs, license installation, and Splunk-2-Splunk configuration.

Splunk's Web interface has a blue (i) button labeled Help in its upper right corner. Click this button to pop up a built-in set of help pages.

Additionally, each page within the Admin area of the interface has blue (i) buttons next to the green title atop each group of controls. Click any one of these (i) buttons to go straight to the help for that part of the page.

From the command line on your Splunk Server host, type this command.
# /opt/splunk/bin/splunk help

At splunk.com

Go to splunk.com/r/support for a directory of all Splunk's help resources.

Updating 2.1.x to 2.2.x

These instructions apply to Splunk 2.1 and later releases. To update a 2.0.x release see the migration instructions.

Step 1

Stop the Splunk Server by running this command on its host.

# $SPLUNK_HOME/bin/splunk stop

Step 2

Create a backup of your $SPLUNK_HOME/etc directory in an alternate location

# cp -r $SPLUNK_HOME/etc /foo/etc.bak

Step 3

Use the upgrade instructions for your package.

RPM

# rpm -U splunk-2.2.i386.rpm

deb

# dpkg -i splunk-2.2-linux-2.6-intel.deb

FreeBSD

# pkg_add splunk-2.2-freebsd-5.4-intel.tgz

MacOS

Double-click on splunk.pkg

When the installer gets to the Select Destination dialog, click Choose... to select a directory other than /Applications

# installer -pkg splunk.pkg

# installer -pkg splunk.pkg -target /Volumes/LaCie\ Disk

-target specifies a target volume, such as another disk, where Splunk will be installed in /Applications/splunk .
To install into a directory other than /Applications/splunk on any volume, use the graphical installer as described above.

Solaris

# pkgadd splunk.pkg

Tarball

Step 4

If you configured multiple users in your 2.1.x Splunk install those users will not be presented after upgrading to 2.2
The users are still stored in the authentication database. This script will allow your 2.2 install to read the users in.

Step 5

If you altered any of the configuration files verify that those changes were not overwritten. Common configuration files that can be overwritten include (but are not limited to):

Step 6

Restart the Splunk Server.

# cd $SPLUNK_HOME/bin/splunk start

2.0.x to 2.1.x Migration Instructions

Migration is the process of converting a Splunk 2.0 index to Splunk 2.1 format.

Migration is a non-reversible operation. The two versions use incompatible storage schema on disk.

Why a migration process?

This is the last time you will have to schedule a migration to upgrade Splunk.

Normally Splunk installations are compatible across release versions. But Splunk 2.1 introduces new search and index features such as delete:: as well as much higher performance. This required us to implement a different data schema on disk. Splunk 2.1 is much more space efficient than Splunk 2.0 - the overall amount of space taken by Splunk Server will usually be less after migration, and the server will run faster as well. To allow these new features to work with 2.0 and earlier data, the Splunk 2.1 server must first migrate 2.0 indexes to the 2.1 schema.

Beginning with Splunk 2.2, indexed data from previous versions of Splunk will continue to be searchable without a migration process. New features may not be available on events indexed with previous versions of Splunk, but no previous functionality on those events will be lost.

How long does it take?

Migrating a 100 million event index takes about 4 hours on typical hardware.

Will I lose my data?

During the migration process, the Splunk Server cannot be searched and any incoming events not cached to file before the Splunk Server indexes them will be permanently lost. This includes syslog port 514, Splunk-2-Splunk connections, and any other events accessed through TCP, UDP or FIFO.

Splunk-2-Splunk connections are not compatible between 2.0 and 2.1 servers. The connection will be down from the time either end is shut down until both ends are back up, and the receiving end has completed migrating its index from 2.0 to 2.1 format.

Avoid data loss

Please review and follow these steps to prevent the Splunk 2.0 to 2.1 migration process from resulting in lost data.

Make a copy first

The most obvious way to avoid data loss is to make a copy of your Splunk 2.0 installation, migrate one copy, and keep the other as a backup. That way, if the non-reversible migration process is interrupted or fails for any reason, you will still have a usable copy of your Splunk 2.0 indexes.

Don't migrate > 100 million events

If your index contains more than 100 million events, the migration program will not work for you. Set up a new, parallel 2.1 server instead of attempting to migrate your 2.0 index to 2.1. Yes, this will require you to search old and new events separately, but it will eliminate the risk of unacceptable downtime.

Splunk-2-Splunk setups

To upgrade Splunk-2-Splunk multi-server configurations from 2.0 to 2.1:

1. Shut down your forwarding server(s) first. Be sure their splunkd processes are stopped. This will prevent them from transmitting data to the receiving server via TCP while it is down.
2. Update the receiving server to 2.1.
3. Restart the receiving server. It will prompt you to migrate its indexes when it first comes up after the upgrade. See the note above on estimated migration time.
4. After the receiving server has migrated its index from 2.0 to 2.1 and returned to normal operation, update and restart each of your forwarding servers.
5. As each forwarding server restarts running Splunk 2.1, it will forward its backlog of event to the 2.1 receiving server.

UDP, TCP, and FIFO inputs

If your Splunk Server receives syslog or other events via UDP or TCP connections rather than indexing them from local files, or if it reads from one or more FIFO queues:

1. Set up an alternate temporary recording mechanism, such as a parallel syslog deamon, to write these events to file.
2. Shut down the Splunk Server and upgrade it from 2.0 to 2.1.
3. After the Splunk Server has migrated its index from 2.0 to 2.1 schema and returned to normal operation, redirect your non-cached inputs to the Splunk Server again.
4. Index any archive files created during the migration process by your alternate service.

Instructions (native package)

1. After backing up the 2.0.X installation, transfer the native package to the
server you wish to migrate.

2. Stop splunk manually:

# $SPLUNK_HOME/bin/splunk stop

The native package will attempt to stop the server for you, but known issues with
the 2.0.X software may prevent it from shutting down. If the 2.0.X
Splunk Server isn't shutting down after being given the stop command, kill
the splunkd processes with kill -9.

3. Using the appropriate command install the 2.1 Splunk Server software over
the 2.0.X installation. The prefix supplied to the native package should be
the absolute path to the splunk directory. For example, if Splunk Server is
installed in /usr/local/splunk then the prefix supplied to the native package
installer should be /usr/local. The default is /opt .

4. Once the native package utility has completed is operation change into
the splunk directory and start the server:

# ./bin/splunk start

a. Splunk will prompt you to confirm the migration process. Answer "y".

b. Splunk will display the Splunk Server 2.1 license agreement. Page through it
and accept the license.

c. Splunk Server 2.1 will first migrate your 2.0.X configuration. It will then migrate
your indexed data in two phases. During this time it will display progress messages.
Migration is not complete and the Splunk Server is not available until the
command line prompt returns.

During migration you may see output that indicates an error, or that files
aren't found. More often than not it only means you didn't have that aspect
of 2.0.X to migrate. Please give the migration process an opportunity to complete and
check your installation before contacting support.

5. Once the splunk start command has completed and your shell prompt has
returned, the migration process is complete. Login to the Splunk Server's web interface.
Spot check your data input configuration and perform some searches to ensure
system responsiveness. If it works as expected, you're done!

Instructions (tar file)

1. After backing up the 2.0.X installation transfer the tar archive to the
server you wish to migrate.

2. Stop splunk manually:

# $SPLUNK_HOME/bin/splunk stop

There are known issues with the 2.0.X software that may prevent it from shutting down. If
the 2.0.X Splunk Server isn't shutting down after being given the stop
command, kill the splunkd processes with kill -9.

3. Create a backup copy of your configuration that Splunk Server will
use as the basis for migration. Change to your splunk directory and make a backup
copy of your confiuration files:

# mv etc etc.bak

Don't deviate from this exact command. When the Splunk Server starts, the old etc directory needs to be gone, and the server will only look for an etc.bak from which to migrate old configuration files. Any change to the above command risks making the server inoperable.

4. Place the tar archive next the existing 2.0.X splunk directory and
extract it. For example, if your splunk directory is /opt/splunk then
you should place the tar archive in /opt and run this command:

# tar xvzf splunk*.tgz

If your tar command doesn't have integrated support for compressed files,
you will need to decompress it first.

5. Change into the splunk directory and follow the instructions in the file README_TAR_INSTALL.

# cd /opt/splunk
# cat README_TAR_INSTALL

6. Start the Splunk Server:

# ./bin/splunk start

a. The Splunk Server will prompt you to confirm the migration process. Answer "y".

b. Splunk will display the Splunk Server 2.1 license agreement. Page through it and accept the license.

c. Splunk Server 2.1 will first migrate your 2.0.X configuration. It will then migrate
your indexed data in two phases. During this time it will display progress messages.
Migration is not complete and the Splunk Server is not available until the
command line prompt returns.

During migration you may see output that indicates an error, or that files
aren't found. More often than not it only means you didn't have that aspect
of 2.0.X to migrate. Please give the migration process an opportunity to complete and
check your installation before contacting support.

7. Once the splunk start command has completed and your shell prompt has
returned, the migration process is complete. Login to the Splunk Server's web interface.
Spot check your data input configuration and perform some searches to ensure
system responsiveness. If it works as expected, you're done!

Parallel 2.0 / 2.1 setup

1. Install Splunk 2.1 in a different directory from Splunk 2.0.

2. Start the 2.1 server. If the Splunk 2.0 server is already running on ports 8000 / 8001 / 8089, the 2.1 server will prompt for different ports.

3. Export the 2.0 server's event type tags and sourcetype renames, if there are any, to a temporary file by running these commands on the 2.0 server. Be sure to use the 2.0 server's .bin/splunk command.

# splunk export -s > /tmp/sourcetypes
# splunk export -t > /tmp/tags

4. Import the event type tags and sourcetype renames by running these commands on the 2.1 server. Be sure to use the 2.1 server's .bin/splunk command.

# splunk import -s < /tmp/sourcetypes
# splunk import -t < /tmp/tags

5. Run the following command on the Splunk 2.1 instance to migrate your environment from your 2.0 installation to your 2.1 install.

# ./splunk migrate env /path/to/2.0/splunk_home

This command will migrate your Saved Splunks, Live Splunks, data input configurations, processing properties and regex definitions. It will not migrate your 2.0.x indexed data. To migrate your indexed data, you will need to do an overlay install as described above.

Help and support

Error messages

We've collected a list of known Installation Errors and their fixes. If you encounter any errors or warnings during the process - or anything that seems wrong - please check there first.

More help

After migration, if your Splunk Server is not functional or some of your data appears to be missing,
please contact Splunk Support with the following information:

1. The OS version and Splunk version you were attempting to migrate from
2. A copy of the CLI output from the splunk start command
3. A copy of splunkd.log from $SPLUNK_HOME/var/log/splunk/splunkd.log
4. A copy of $SPLUNK_HOME/etc/myinstall/pluginConfs/multiIndexer.xml

This information will enable Splunk to respond to your support request
in a timely and efficient manner. Call your support representative or
email support@splunk.com.

More Help

Splunk-2-Splunk Setup

2.0 Splunk-2-Splunk migration

If you have a network of Splunk 2.0.x servers configured for Splunk-2-Splunk distributed data access, see the 2.0 to 2.1 Migration Instructions.

Splunk 2.1 lets you configure Splunk-2-Splunk data forwarding, data receving and distributed search on the Admin page of Splunk's GUI, or through the command line interface. Both have built-in help. The GUI displays a diagram of which servers are fowarding, receiving, or handling distributed searches.

Browser-based configuration

Command line configuration

Type this command to see built-in help for configuring the Splunk Server:

# /opt/splunk/bin/splunk help s2s

Below are the built-in command line help entries related to Splunk-2-Splunk configuration.

s2s (splunk-2-splunk)

Splunk-2-Splunk configuration management
These commands require a Splunk Professional license.

Actions

Objects

broadcast availability for Distributed Search from other Splunk Servers

distribute searches to other Splunk Servers

reception of data to be indexed from other Splunk Servers

a Splunk Server to which to forward data to be indexed

a Splunk Server to which to forward searches

Default Parameter

Required Parameters

Optional Parameters

Type "help [object]" to see the parameters specific to each type of object.

Examples

# splunk enable listen 18089
# splunk enable discoverable -auth gwb:d3cidr

search-server

Splunk-2-Splunk distributed search configuration management
These commands require a Splunk Professional license.

Actions & Objects

Default Parameter

the Splunk Server name of the server to configure

Required Parameters

Optional Parameters

username:password to authenticate the command to a Splunk Professional server

Examples

# splunk add search-server production02 -auth gwb-d3cidr

forward-server

Splunk-2-Splunk data forwarding configuration management
These commands require a Splunk Professional license.

Actions

Default Parameter

the Splunk Server name of the server to configure

Required Parameter

Optional Parameters

username:password to authenticate the command to a Splunk Professional server

Examples

# splunk add forward-server production02 -auth gwb:d3cidr

enable, disable, display, discoverable, listen, dist-search

Actions

Objects

broadcast availability for Distributed Search from other Splunk Servers

distributed searches to other Splunk Servers

reception of data to be indexed from other Splunk Servers

Default Parameter

TCP port number on which to listen for data from other Splunk Servers - default is 8089

Required Parameters

Optional Parameters

username:password to authenticate the command to a Splunk Professional server

Examples

# splunk enable listen
# splunk enable listen 18089
# splunk enable listen -source 18089 (same thing, since -source is the default parameter)
# splunk enable discoverable -auth gwb:d3cidr

Uninstall

Use your local package management commands to uninstall Splunk. In most cases, files not originally installed by the package will be retained. This usually means your configuration and index files, which are under the same directory (default /opt/splunk) as the rest of the installation by default.

RedHat Linux

# rpm --erase splunk-2.1-0

Debian Linux

# dpkg -r splunk

Solaris

# pkgrm splunk

FreeBSD

# pkg_delete splunk

In most cases, files not originally installed by the rpm package will be retained. This usually means your configuration and index files, which are under the same directory (default ///opt/splunk) as the rest of the installation by default.

Manual uninstall

If you can't use package management commands, these commands will remove the installed components except for any init scripts you've created.

# kill -9 `ps -ef | grep splunk | grep -v grep | awk '{print $1}'`
# rm -rf /opt/splunk      (or wherever you installed Splunk)
# rm -rf /opt/splunkdata   (if you set up datastore or indexes outside the top-level directory)
# userdel splunk
# groupdel splunk

Troubleshooting Installation Errors

This page is a collection of error messages customers have reported during or after installing Splunk 2.1. If you encounter installation errors not covered on this page, please let us know at support@splunk.com or on our Support Forums.

Splunkd appears to be down

The usual cause at installation time is that the server host has no entry for localhost in /etc/hosts. Either add one, or edit this line in the file /opt/splunk/etc/myinstall/search.xml to replace localhost with 127.0.0.1 or a DNS-supported hostname.

<managerURL>``http://localhost:8089``</managerURL>

If this isn't the problem, see the full help page on Splunkd appears to be down.

useradd: warning: the home directory already exists

This message may appear if you install the Splunk Server over a previously uninstalled version that still retains a skeletal file structure. The message can be ignored. However, make sure you don't have both a $SPLUNK_HOME/etc and a $SPLUNK_HOME/etc.bak directory if you are trying to migrate to version 2.1. The migration process will use the configuration files in etc if they're still there, rather than migrating from etc.bak.

python: syntax error at line 1: `(' unexpected

You may have installed the wrong version of Splunk. Make sure you aren't trying to run the Solaris Intel version on a SPARC server.

FreeBSD memory constraint

Please be aware of the setting:

kern.maxdsize=4G

that should be present in

/boot/loader.conf

Without it, a Splunk instance that's using more than the usual amount of memory (e.g., has multiple user-defined indices, many files being tailed simultaneously) will experience severe performance porblems