Agent User Guide

Agent User Guide

Before Start

Freezer will automatically add prefix “freezer” to the container name, where it is provided by the user and doesn’t already start with this prefix. If no container name is provided, the default is “freezer_backups”.

The execution options can be set from the command line and/or config file in ini format. There’s an example of the job config file available in freezer/freezer/specs/job-backup.conf.example.

Command line options always precedes options in config file.

Backup Options

Freezer Agent can be used as standalone backup tool from command line. In it is most simple form, you can run commands to backup your data to OpenStack Swift, local directory, remote SSH or S3 compatible storage.

Basic File System Backup

Here is the most basic use example:

# On Linux
sudo freezer-agent --path-to-backup [/data/dir/to/backup] \
--container freezer_[new-data-to-backup] --backup-name [my-backup-name]

# On Windows (need admin rights)
freezer-agent --action backup --mode fs --backup-name [testwindows] \
--path-to-backup "[C:\path\to\backup]" --container freezer_[new-windows-backup] \
--log-file  [C:\path\to\log\freezer.log]

By default –mode fs is set. The command would generate a compressed tar gzip file of the directory “/data/dir/to/backup”. The generated file will be segmented in stream and uploaded in the swift container called freezer_new-data-backup, with backup name my-backup-name.

Now you can check /var/log/freezer.log file or in Windows C:pathtologfreezer.log if your backup job finished successfully.

MongoDB Backup With LVM Snapshot

If backed up system has LVM system, Freezer can use LVM Snapshot feature to freezes the file system. This will prevent data corruption for volumes that contains data bases.

First let’s check where your MongoDB database files are located:

mount -l

Once we know the volume on which our Mongo data is mounted, we can get the volume group and logical volume info:

sudo vgdisplay

sudo lvdisplay

Now let’s start MongoDB backup with LVM Snapshot:

sudo freezer-agent --lvm-srcvol [logical/volume/path] \
--lvm-dirmount /var/lib/snapshot-backup \
--lvm-volgroup [lvm-group-name] \
--path-to-backup /var/lib/snapshot-backup/mongod_ops2 \
--container freezer_[container-name-for-new-backup] \
--exclude "*.lock" --mode mongo --backup-name [name-for-new-backup]

Now freezer-agent creates an LVM snapshot of the volume [logical/volume/path]. If no options are provided, the default snapshot name is “freezer_backup_snap”. The snapshot volume will be mounted automatically on /var/lib/snapshot-backup and the backup metadata and segments will be uploaded in the container freezer_[container-name-for-new-backup] with the name [name-for-new-backup].

System Backup With LVM Snapshot

Freezer can take full system backup with LVM Snapshot:

sudo freezer-agent --lvm-srcvol [logical/volume/path] \
--lvm-dirmount /var/snapshot-backup \
--lvm-volgroup jenkins \
--path-to-backup /var/snapshot-backup \
--container freezer_jenkins-backup-prod \
--exclude "\*.lock" \
--mode fs \
--backup-name jenkins-ops2

MySQL Backup With LVM Snapshot

MySQL backup require a basic configuration file. The following is an example of the config.

Create following config file:

sudo vi /root/.freezer/db.conf
host = []
user = [mysql-user-name]
password = [mysql-user-password]

Execute a MySQL backup using LVM Snapshot:

sudo freezer-agent --lvm-srcvol /dev/mysqlvg/mysqlvol \
--lvm-dirmount /var/snapshot-backup \
--lvm-volgroup mysqlvg \
--path-to-backup /var/snapshot-backup \
--mysql-conf /root/.freezer/freezer-mysql.conf \
--container freezer_mysql-backup-prod \
--mode mysql \
--backup-name mysql-ops002

Cinder Backups

Cinder has its own mechanism for backups, and freezer supports it. But it also allows creating a glance image from volume and uploading to swift.

To use standard cinder backups please provide –cindernative-vol-id argument.

To make a cinder backup you should provide cinder-vol-id or cindernative-vol-id parameter in command line arguments. Freezer doesn’t do any additional checks and assumes that making a backup of that image will be sufficient to restore your data in future.

Execute a cinder backup:

freezer-agent --cinder-vol-id [cinder-volume-id]

Execute a MySQL backup with cinder:

freezer-agent --mysql-conf /root/.freezer/freezer-mysql.conf \
--container freezer_mysql-backup-prod \
--mode mysql \
--backup-name mysql-ops002 \
--cinder-vol-id [cinder-volume-id]

Nova Backups

If you provide nova argument in parameters, freezer assumes that all necessary data is located on instance disk and it can be successfully stored using nova snapshot mechanism.

For example if we want to store our mysql located on instance disk, we will execute the same actions like in the case of lvm or tar snapshots, but we will invoke nova snapshot instead of lvm or tar.

After that we will place snapshot to swift container as dynamic large object.

container/%instance_id%/%timestamp% <- large object with metadata container_segments/%instance_id%/%timestamp%/segments…

Restore will create a snapshot from stored data and restore an instance from this snapshot. Instance will have different id and old instance should be terminated manually.

To make a nova backup you should provide a nova parameter in the arguments. Freezer doesn’t do any additional checks and assumes that making a backup of that instance will be sufficient to restore your data in future.

Execute a nova backup:

freezer-agent --nova-inst-id [nova-instance-id]

Execute a MySQL backup with nova:

freezer-agent --mysql-conf /root/.freezer/freezer-mysql.conf \
--container freezer_mysql-backup-prod \
--mode mysql \
--backup-name mysql-ops002 \
--nova-inst-id [nova-instance-id]

Note: All the freezer-agent activities are logged into /var/log/freezer.log.

Storage Options

Freezer can use following storage technologies to backup the data:

  • OpenStack Swift Object Storage
  • Local Directory (Can be NFS mounted directory)
  • SSH

Swift Object Storage Backup/Restore

Default storage option for Freezer is Swift. If you do not specify “–storage” option Freezer will use Swift Object Storage. “–storage swift” option can be specified in order to use Swift.

Backup example:

sudo freezer-agent --path-to-backup [/data/dir/to/backup] \
--container freezer-[container] --backup-name [my-backup-name] \
--storage swift

Restore example:

sudo freezer-agent --action restore --restore-abs-path [/data/dir/to/backup] \
--container freezer-[container] [--backup-name my-backup-name] \
--storage swift

Local Storage Backup/Restore

Freezer can use local directory as target backup location. This directory can be NFS,CIFS,SAMBA or other network file systems mounted directory.

To use local storage “–storage local” must be specified. And “–container %path-to-folder-with-backups%” option must be present.

Backup example:

sudo freezer-agent --path-to-backup [/data/dir/to/backup] \
--container /tmp/my_backup_path/ [--backup-name my-backup-name] \
--storage local

Restore example:

sudo freezer-agent --action restore \
--restore-abs-path [/data/dir/to/backup] \
--container /tmp/my_backup_path/ \
--backup-name [my-backup-name] \
--storage local

SSH Storage Backup/Restore

Freezer can use ssh to backup the data in fould on remote server. This option will turn any Linux server to backup storage.

To use ssh storage specify “–storage ssh” And use “–container %path-to-folder-with-backups-on-remote-machine%” Also you should specify ssh-username, ssh-key and ssh-host parameters. ssh-port is optional parameter, default is 22.

In order to use SSH to backup, “–storage ssh” and “–container %path-to-folder-with-backups-on-remote-machine%” options must be specified. Also ssh-username, ssh-host parameters must be supplied. ssh-port parameter is optional and Freezer use default ssh port 22 if not specified.

Backup example:

sudo freezer-agent --path-to-backup [/data/dir/to/backup] \
--container /remote-machine-path/ \
--backup-name my-backup-name \
--storage ssh --ssh-username [ssh-user-name] --ssh-key ~/.ssh/id_rsa \

Restore example:

sudo freezer-agent  --action restore \
--restore-abs-pat [/data/dir/to/backup] \
--container /remote-machine-path/ \
--backup-name my-backup-name \
--storage ssh --ssh-username ubuntu --ssh-key ~/.ssh/id_rsa \



  • As a general rule, when you execute a restore, the application that writes or reads data should be stopped.
  • There are 3 main options that need to be set for data restore

File System Restore

Following example shows how to restore backup named “adminui.git”:

sudo freezer-agent --action restore --container freezer_adminui_git \
--backup-name adminui.git \
--hostname [hostname-of-the-server] \
--restore-abs-path /home/git/repositories/adminui.git/ \
--restore-from-date "2014-05-23T23:23:23"

MySQL Restore

Execute a MySQL restore of the backup name holly-mysql.

Let’s stop mysql service first:

sudo service mysql stop

Execute restore:

sudo freezer-agent --action restore \
--container freezer_foobar-container-2 \
--backup-name mysql-prod --hostname [server-host-name] \
--restore-abs-path /var/lib/mysql \
--restore-from-date "2014-05-23T23:23:23"

Start MySQL:

sudo service mysql start

MongoDB Restore

Execute a MongoDB restore of the backup name mongobigdata:

sudo freezer-agent --action restore \
--container freezer_foobar-container-2 \
--backup-name mongobigdata \
--hostname db-HP-DL380-host-001
--restore-abs-path /var/lib/mongo \
--restore-from-date "2014-05-23T23:23:23"

Cinder Restore

Cinder restore currently creates a volume with the contents of the saved one, but doesn’t implement deattach of existing volume and attach of the new one to the vm.

You should implement these steps manually. To create a new volume from existing content run next command:

freezer-agent --action restore --cinder-vol-id [cinder-volume-id]

freezer-agent --action restore --cindernative-vol-id [cinder-volume-id]

Nova Restore

Nova restore currently creates an instance with the content of saved one, but the ip address of the vm will be different as well as it’s id.

Execute a nova restore:

freezer-agent --action restore --nova-inst-id [nova-instance-id]

Local Storage Restore

sudo freezer-agent --action restore --container /local_backup_storage/ \
--backup-name adminui.git \
--hostname git-HP-DL380-host-001 \
--restore-abs-path /home/git/repositories/adminui.git/ \
--restore-from-date "2014-05-23T23:23:23" \
--storage local

Parallel Backup

Parallel backup can be executed only by config file. In config file you should create n additional sections that start with “storage:”


[storage:my_storage1], [storage:ssh], [storage:storage3]

Each storage section should have ‘container’ argument and all parameters related to the storage.


ssh-username, ssh-port

For swift storage you should provide additional parameter called ‘osrc’ Osrc should be a path to file with OpenStack Credentials like:

export OS_AUTH_URL=http://[keystone_url]:5000/v3
export OS_PROJECT_NAME=[project_name]
export OS_USERNAME=[username]
export OS_PASSWORD=[password]
export OS_USER_DOMAIN_NAME=Default
export OS_CACERT=/etc/ssl/certs/ca-certificates.crt

Example of Config file for two local storages and one swift storage:

action = backup
mode = fs
path_to_backup = /foo/
backup_name = mytest6
always_level = 2
max_segment_size = 67108864
container = /tmp/backup/
storage = local

container = /tmp/backup1/

container = /tmp/backup2/

container = test
osrc = openrc.osrc

Freezer Scheduler

The freezer-scheduler is one of the two freezer components which is run on the client nodes; the other one being the freezer-agent. It has a double role: it is used both to start the scheduler process, and as a cli-tool which allows the user to interact with the API.

The freezer-scheduler process can be started/stopped in daemon mode using the usual positional arguments:

freezer-scheduler start|stop

It can be also be started as a foreground process using the –no-daemon flag:

freezer-scheduler --no-daemon start

This can be useful for testing purposes, when launched in a Docker container, or by a babysitting process such as systemd.

The cli-tool version is used to manage the jobs in the API. A “job” is basically a container; a document which contains one or more “actions”. An action contains the instructions for the freezer-agent. They are the same parameters that would be passed to the agent on the command line. For example: “backup_name”, “path_to_backup”, “max_level”

To sum it up, a job is a sequence of parameters that the scheduler pulls from the API and passes to a newly spawned freezer-agent process at the right time.

The scheduler understands the “scheduling” part of the job document, which it uses to actually schedule the job, while the rest of the parameters are substantially opaque.

It may also be useful to use the “-c” parameter to specify the client-id that the scheduler will use when interacting with the API.

The purpose of the client-id is to associate a job with the scheduler instance which is supposed to execute that job.

A single openstack user could manage different resources on different nodes (and actually may even have different freezer-scheduler instances running on the same node with different local privileges, for example), and the client-id allows him to associate the specific scheduler instance with its specific jobs.

When not provided with a custom client-id, the scheduler falls back to the default which is composed from the tenant-id and the hostname of the machine on which it is running.

The first step to use the scheduler is creating a document with the job:

vi test_job.json

  "job_actions": [
          "freezer_action": {
              "action": "backup",
              "mode": "fs",
              "backup_name": "backup1",
              "path_to_backup": "/home/me/datadir",
              "container": "schedule_backups",
              "log_file": "/home/me/.freezer/freezer.log"
          "max_retries": 3,
          "max_retries_interval": 60
  "job_schedule": {
      "schedule_interval": "4 hours",
      "schedule_start_date": "2015-08-16T17:58:00"
  "description": "schedule_backups 6"

Then upload that job into the API:

freezer-scheduler -c node12 job-create --file test_job.json

The newly created job can be found with:

freezer-scheduler -c node12 job-list

Its content can be read with:

freezer-scheduler -c node12 job-get -j [job_id]

The scheduler can be started on the target node with:

freezer-scheduler -c node12 -i 15 -f ~/job_dir start

The scheduler could have already been started. As soon as the freezer-scheduler contacts the API, it fetches the job and schedules it.



To get an updated sample of freezer-scheduler configuration you the following command:

oslo-config-generator --config-file config-generator/scheduler.conf

Update sample file will be generated in etc/scheduler.conf.sample


To list options available in freezer-agent use the following command:

oslo-config-generator --namespace freezer --namespace oslo.log

this will print all options to the screen you direct the output to a file if you want:

oslo-config-generator --namespace freezer --namespace oslo.log --output-file etc/agent.conf.sample

Dependencies Notes

In stable/kilo and stable/liberty the module peppep3134daemon is imported from local path rather than pip. This generated many issues as the package is not in the global-requirements.txt of kilo and liberty. Also pbr in the kilo release does not support env markers which further complicated the installation.

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.