freezer/doc/source/user/freezer-agent.rst

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 its most simple form, you can run commands to backup your data to OpenStack Swift, local directory, remote SSH(SFTP) or S3 compatible storage or remote FTP or FTPS 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 = [your.mysql.host.ip]
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 --mode cinder --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 --backup-name [my-backup-name] \
--mode nova --engine nova \
--no-incremental True \
--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.

Glance Backups

If you provide glance backup argument in parameters, freezer will backup image using glance download_image API to storage.

Restore will create a image from stored data using glance create_image API . Image will have different id from original one.

Backup example:

Execute a glance backup with image-id:

freezer-agent --backup-name [my-backup-name] \
--mode glance --engine_name glance \
--action backup \
--no-incremental True \
--container /home/freezer_data \
--storage local \
--glance_image_id [glance-image-id]

Execute a glance backup with image-name:

freezer-agent --backup-name [my-backup-name] \
--mode glance --engine_name glance \
--action backup \
--no-incremental True \
--container /home/freezer_data \
--storage local \
--glance_image_name [glance-image-name]

Execute a glance backup with image-name-filter:

freezer-agent --backup-name [my-backup-name] \
--mode glance --engine_name glance \
--action backup \
--no-incremental True \
--container /home/freezer_data \
--storage local \
--glance_image_name_filter [glance-image-name-filter]

Execute a glance backup with project_id:

freezer-agent --backup-name [my-backup-name] \
--mode glance --engine_name glance \
--action backup \
--no-incremental True \
--container /home/freezer_data \
--storage local \
--project_id [project-id]

Restore example:

Execute a glance restore with image-id:

freezer-agent --backup-name [my-backup-name] \
--mode glance --engine_name glance \
--action restore \
--no-incremental True \
--container /home/freezer_data \
--storage local \
--glance_image_id [glance-image-id]

Execute a glance restore with image-name:

freezer-agent --backup-name [my-backup-name] \
--mode glance --engine_name glance \
--action restore \
--no-incremental True \
--container /home/freezer_data \
--storage local \
--glance_image_name [glance-image-name]

Execute a glance restore with image-name-filter:

freezer-agent --backup-name [my-backup-name] \
--mode glance --engine_name glance \
--action restore \
--no-incremental True \
--container /home/freezer_data \
--storage local \
--glance_image_name_filter [glance-image-name-filter]

Execute a glance restore with project_id:

freezer-agent --backup-name [my-backup-name] \
--mode glance --engine_name glance \
--action restore \
--no-incremental True \
--container /home/freezer_data \
--storage local \
--project_id [project-id]

Storage Options

Freezer can use following storage technologies to backup the data:

• OpenStack Swift Object Storage
• Local Directory (Can be NFS mounted directory)
• SSH(SFTP)(Can be mounted without password(ssh-key) or with password)

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(SFTP) Storage Backup/Restore

Freezer can use SSH(SFTP) to backup the data to remote server. This option will turn any Linux server to backup storage.

To use SSH(SFTP) storage specify "--storage ssh" And use "--container %path-to-folder-with-backups-on-remote-machine%" Also you should specify ssh-username, ssh-key(or ssh-password) and ssh-host parameters. ssh-port is an 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 example1 (without password(ssh-key)):

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 \
--ssh-host 8.8.8.8

Restore example1 (without password(ssh-key)):

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

Backup example2 (with password):

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-password passwd_test \
--ssh-host 8.8.8.8

Restore example2 (with password):

sudo freezer-agent  --action restore \
--restore-abs-path [/data/dir/to/backup] \
--container /remote-machine-path/ \
--backup-name my-backup-name \
--storage ssh --ssh-username ubuntu --ssh-password passwd_test \
--ssh-host 8.8.8.8

FTP Storage Backup/Restore

Freezer can use FTP to backup the data to remote server. This option will turn any FTP server to backup storage.

To use FTP storage specify "--storage ftp" And use "--container %path-to-folder-with-backups-on-remote-machine%" Also you should specify ftp-username, ftp-password and ftp-host parameters. ftp-port is optional parameter, default is 21.

In order to use FTP to backup, "--storage ftp" and "--container %path-to-folder-with-backups-on-remote-machine%" options must be specified. Also ftp-username, ftp-password, ftp-host parameters must be supplied. ftp-port parameter is optional and Freezer use default ssh port 21 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 ftp --ftp-username [ftp-user-name] \
--ftp-password [ftp-user-password] \
--ftp-host 8.8.8.8 \
--ftp-port 21

Restore example:

sudo freezer-agent  --action restore \
--restore-abs-pat [/data/dir/to/backup] \
--container /remote-machine-path/ \
--backup-name my-backup-name \
--storage ftp \
--ftp-username [ftp-user-name] \
--ftp-password [ftp-user-password] \
--ftp-host 8.8.8.8
--ftp-port 21

FTPS Storage Backup/Restore

Freezer can use FTPS to backup the data to remote server. This option will turn any FTPS server to backup storage.

To use FTPS storage specify "--storage ftps" And use "--container %path-to-folder-with-backups-on-remote-machine%" Also you should specify ftp-username, ftp-password and ftp-host parameters. ftp-port is optional parameter, default is 21.

In order to use FTPS to backup, "--storage ftps" and "--container %path-to-folder-with-backups-on-remote-machine%" options must be specified. Also ftp-username, ftp-password, ftp-host parameters must be supplied. ftp-port parameter is optional and Freezer use default ssh port 21 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 ftps \
--ftp-username [ftp-user-name] \
--ftp-password [ftp-user-password] \
--ftp-host 8.8.8.8 \
--ftp-port 21

Restore example:

sudo freezer-agent  --action restore \
--restore-abs-pat [/data/dir/to/backup] \
--container /remote-machine-path/ \
--backup-name my-backup-name \
--storage ftps \
--ftp-username [ftp-user-name] \
--ftp-password [ftp-user-password] \
--ftp-host 8.8.8.8
--ftp-port 21

Restore

NOTES:

• 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:"

Example:

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

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

Example:

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:

unset OS_DOMAIN_NAME
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_PROJECT_DOMAIN_NAME=Default
export OS_USER_DOMAIN_NAME=Default
export OS_IDENTITY_API_VERSION=3
export OS_AUTH_VERSION=3
export OS_CACERT=/etc/ssl/certs/ca-certificates.crt
export OS_ENDPOINT_TYPE=publicURL

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

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

[storage:first]
storage=local
container = /tmp/backup1/

[storage:second]
storage=local
container = /tmp/backup2/

[storage:swift]
storage=swift
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 job-create --client node12 --file test_job.json

The newly created job can be found with:

freezer job-list --client node12

Its content can be read with:

freezer job-get [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.

MISC

Scheduler

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

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

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

Agent

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.

Copyright

The Freezer logo is released under the licence Attribution 3.0 Unported (CC BY3.0).