Upgrading from a previous release

Upgrading post version 2.0.0

When updating your Cuckoo from a >=2.0.0 version, Cuckoo will automatically try to upgrade your Cuckoo Working Directory (CWD). If any actions are required, such as running automatically database migrations or backing up an edited file in your CWD, Cuckoo will notify you.

To start an upgrade after updating Cuckoo, simply start Cuckoo as you normally would.

Upgrading to Cuckoo from legacy Cuckoo

Legacy Cuckoo is any Cuckoo version older than 2.0.0. These versions use a working directory inside of the Cuckoo installation path. Newer Cuckoo versions use a Cuckoo Working Directory.

This document describes the process of importing an older legacy Cuckoo setup in order to upgrade your Cuckoo to the latest and greatest version. This importing process is possible for Cuckoo 0.6 and upwards. Naturally it doesn’t re-apply any custom code changes that you applied to your old setup, but it does migrate your database, configuration, and analyses to the new version (in a best-effort manner).

Now, in order to upgrade your setup, you’ll simply have to perform the following steps:

  1. Come up with a Cuckoo Working Directory for the new setup (although the default one should work just fine, assuming it doesn’t exist yet).
  2. Optionally create a backup of your data (Cuckoo will also offer to do this for you before doing the actual setup import).
  3. Run the cuckoo import command.

The cuckoo import command

The cuckoo import App performs a number of steps in order to import an older setup. Previously we had manual steps for performing a database migration, these have been integrated in the import process as well.

Note

Only use the import command if you are upgrading from a Cuckoo version pre 2.0.0.

The usage of cuckoo import is as follows:

$ cuckoo import --help
Usage: cuckoo import [OPTIONS] PATH

  Imports an older Cuckoo setup into a new CWD. The old setup should be
  identified by PATH and the new CWD may be specified with the --cwd
  parameter, e.g., "cuckoo --cwd /tmp/cwd import old-cuckoo".

Options:
  --copy     Copy all existing analyses to the new CWD (default)
  --move     Move all existing analyses to the new CWD
  --symlink  Symlink all existing analyses to the new CWD
  --help  Show this message and exit.

As per the limited usage documentation of this command, there is an input and an output directory and a couple of different modes. The rest is done by cuckoo import according to best-practice manners.

The three different modes are best described as follows. Keep in mind that these modes only inform the importing process on what to do with the existing analyses and, in the case of sqlite3 usage, the database file. These modes do not apply to any other used databases or data not mentioned in this document.

  • copy: Copies all the analyses from the old setup to the new CWD. In this mode the old storage/ folder will be copied to $CWD/storage/. The copy mode is useful if you want to maintain a backup of the old setup and its analyses, allowing one to restore it with the appropriate SQL backup. Note that this mode will double the size of your existing analyses directory as it does a full copy.
  • move: Moves all the analyses from the old setup to the new CWD. In this mode the old storage/ folder is moved to $CWD/storage/. After the import process you won’t have a backup of your old data anymore, but you will be able to reference to it in the new CWD / setup.
  • symlink: Creates a symbolic link from each analysis in the old setup, i.e., storage/analyses/XYZ, to the new CWD, i.e., $CWD/storage/XYZ. This method is the most desired (as you’ll be able to access the existing analyses in both the old setup as well as the new CWD), but doesn’t work on Windows.

The default mode is copy due to its feature of remaining available on both the old setup as well as the new CWD as well as being cross-platform (i.e., symlink mode isn’t supported on Windows). After reading this documentation one may opt to go for symlink or move mode on non-Windows systems and move mode on Windows systems, though.

Following are the steps taken by Cuckoo when performing an import:

  • The user has to accept a non-binding EULA-like agreement that (just kidding) attempts to inform him or her regarding the implications of importing an older setup.
  • The version of the old Cuckoo setup is identified.
  • It is ensured that the new CWD does not already exist.
  • The old Cuckoo Configuration is read, migrated, and then validated to be fit for usage with the new Cuckoo version, i.e., you can configure a Cuckoo 0.6 setup and migrate it all the way to the latest version and it will simply work.
  • The new CWD is created and it is configured with the migrated configuration.
  • The user is prompted to optionally create a SQL database backup. On Linux-based systems this should work out of the box (and you’ll get a hard error otherwise), but due to issues with $PATH this may require manually fixing up the command on Windows & Mac OS X systems.
  • After the ability to create a SQL database backup, the database schema is migrated to the latest version in-place, i.e., you will not be able to use your old Cuckoo setup with this database anymore (hence the backup).
  • Any and all existing analyses are imported to the new CWD using the mode as specified, or if it has not been specified, the default copy method.

You are now the happy owner of an up-to-date Cuckoo setup. Please inform us of any feedback that you may have through one of the various communication channels that we’ve put in-place.

Warning

One should not clean the old Cuckoo setup after the import. By attempting to do so you may lose the existing analyses (if symlink mode is used) and the SQL, MongoDB, and ElasticSearch databases.