Upgrade

Please note! This wiki is no longer maintained. Our documentation has moved to https://securityonion.net/docs/. Please update your bookmarks. You can find the latest version of this page at: https://securityonion.net/docs/Upgrade.

Security Onion Update Procedure

soup - Security Onion UPdate

We recommend using our soup script to update. Soup will automatically install all available package updates (from both Ubuntu and Security Onion) and all updated Docker images.

sudo soup

Please pay attention to the output of this command as it may request that you take specific action, such as manually restarting services. Also refer to the relevant blog entry for the update as there may be additional information there: https://blog.securityonion.net

Snort/Suricata

Snort package upgrades will back up each of your existing snort.conf files to snort.conf.bak and migrate your HOME_NET and EXTERNAL_NET variables.

Suricata package upgrades will back up each of your existing suricata.yaml files to suricata.yaml.bak and migrate your HOME_NET and EXTERNAL_NET variables.

You'll then need to do the following:

• re-apply any other local customizations to your snort.conf/suricata.yaml file(s)
• update ruleset and restart Snort/Suricata as follows:

sudo rule-update

Bro

Bro package upgrades will attempt to migrate your Bro config. You should double-check your config and see if there are any local customizations that you need to manually re-apply. Then restart Bro as follows:

sudo so-bro-restart

MySQL

If you get any errors relating to MySQL, please see MySQL-Upgrade-Errors.

HWE

If you're running an older 14.04 release, you may need to manually upgrade your HWE stack.

Initiating an update over SSH

If you're updating your Security Onion box over an SSH connection and your connection drops, then your update process may be left in an inconsistent state. It is therefore recommended to run byobu so that your session will continue to run on the Security Onion box even if your connection drops. Byobu is very handy and we recommend running it all the time to avoid forgetting about it before an update.

# install byobu
sudo apt-get install byobu

# enable byobu
byobu-enable

# you're now ready to update

For more information about byobu, please see: https://help.ubuntu.com/community/Byobu

Distributed deployments

If you have a distributed deployment with a master server and separate sensor boxes and/or storage nodes, always update the master server first before updating other boxes. Then make sure to update the remaining boxes shortly thereafter. This will help to ensure that all boxes in your deployment are running the same code versions and help to avoid any incompatibilities.

Using salt and soup to Update your entire Deployment

salt and soup

Standard Ubuntu package management tools

The soup command described above is the recommended method to install updates. If you instead choose to use standard Ubuntu package management tools to install updates, there are some caveats to be aware of:

• Docker - Ubuntu package management tools don't update our Docker images (used for the Elastic Stack currently)

• MySQL - if you've already run Setup, please see the recommended procedure for updating the MySQL packages.

• PF_RING and new kernel packages You may be prompted to update your kernel packages and PF_RING at the same time. If you do so, the PF_RING kernel module may get built for your current kernel and not for the newly installed kernel and upon reboot services will fail. To avoid this, you should install just the PF_RING kernel module by itself and then install the kernel and any other remaining package updates. Here's a one-liner that will do that:

sudo apt-get update ; sudo apt-get install securityonion-pfring-module ; sudo apt-get dist-upgrade

If you accidentally install both the kernel and PF_RING packages at the same time and then reboot and find out that PF_RING services (Snort and Suricata) are failing, you can reinstall the securityonion-pfring-module package:

sudo apt-get install --reinstall securityonion-pfring-module

Security Onion 14.04

Please note: If you're still running the old Security Onion 14.04, soup will continue to install Ubuntu updates until Ubuntu stops releasing updates for 14.04. However, there won't be any more Security Onion updates for version 14.04 as all development will be on version 16.04 moving forward. Please see the bottom of this page for information on upgrading from 14.04 to 16.04.

Upgrades

To upgrade from Security Onion 14.04 to Security Onion 16.04, please see Upgrading-from-14.04-to-16.04.