============= Test Scenario ============= Summary ======= * Intro * 1. Setup Devstack machine with swift and elasticsearch * 2. Setup the client machine * 3. Freezer test scenarios * 4. Automated Integration Tests Intro ===== Test environment nodes layout: 1) Server Machine (192.168.20.100) * devstack * elasticsearch * freezer api 2) Client Machine(s) * freezerc * freezer-scheduler Freezer requires Python version 2.7. Using a virtualenv is also recommended The devstack, elasticsearch and freezer-api services can also be distributed across different nodes. In this example the server machine has a (main) interface with ip 192.168.20.100 1. Setup Devstack machine with swift and elasticsearch ====================================================== 1.1 devstack ------------ Install devstack with swift support. See https://docs.openstack.org/devstack/latest/ :: $ cat local.conf LOGDAYS=1 LOGFILE=$DEST/logs/stack.sh.log SCREEN_LOGDIR=$DEST/logs/screen ADMIN_PASSWORD=quiet DATABASE_PASSWORD=$ADMIN_PASSWORD RABBIT_PASSWORD=$ADMIN_PASSWORD SERVICE_PASSWORD=$ADMIN_PASSWORD SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50 SWIFT_REPLICAS=1 SWIFT_DATA_DIR=$DEST/data/swift SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5 enable_service s-proxy s-object s-container s-account 1.1.1 OpenStack variables ------------------------- Quick script to set OS variables: :: $ cat > ~/os_variables #!/bin/bash # optional parameters: # 1 - os_tenant_name # 2 - os_user_name # 3 - os_auth_url # export OS_TENANT_NAME=${1:-admin} export OS_USERNAME=${2:-admin} export ADDR=${3:-192.168.20.100} export OS_REGION_NAME=RegionOne export OS_PASSWORD=quiet export OS_AUTH_URL=http://${ADDR}:5000/v2.0 export OS_TENANT_ID=`openstack project list | awk -v tenant="$OS_TENANT_NAME" '$4==tenant {print $2}'` env | grep OS_ 1.1.2 register freezer service in keystone ------------------------------------------ :: export my_devstack_machine=192.168.20.100 openstack user create --password FREEZER_PWD freezer openstack role add --user freezer --project service admin openstack service create --name freezer \ --description "Freezer Backup Service" backup openstack endpoint create --region regionOne \ --publicurl http://${my_devstack_machine}:9090 \ --internalurl http://${my_devstack_machine}:9090 \ --adminurl http://${my_devstack_machine}:9090 backup 1.1.3 add a user for the tests in keystone ------------------------------------------ :: source os_variables openstack project create --description "Testing project for Freezer" fproject openstack user create --password quiet fuser openstack role add --project fproject --user fuser Member openstack role add --project fproject --user fuser admin 1.2 Elasticsearch ----------------- visit https://www.elastic.co for installation instruction Relevant lines in /etc/elasticsearch/elasticsearch.yml :: cluster.name: elasticfreezer # choose you own network.host: 192.168.20.100 1.3 Python Virtualenv --------------------- Not required, but recommended :: apt-get install virtualenv virtualenv ~/.venv source ~/.venv/bin/activate 1.4 Freezer Service ------------------- 1.4.1 Freezer API installation steps and requirements ----------------------------------------------------- :: cd ~ && source ~/.venv/bin/activate git clone https://github.com/openstack/freezer.git cd freezer/freezer_api pip install -r requirements.txt python setup.py install 1.4.2 Freezer API Configuration ------------------------------- :: $ cat /etc/freezer-api.conf [DEFAULT] verbose = false logging_file = freezer-api.log [keystone_authtoken] identity_uri = http://192.168.20.100:35357/ www_authenticate_uri = http://192.168.20.100:5000/ admin_user = freezer admin_password = FREEZER_PWD admin_tenant_name = service include_service_catalog = False delay_auth_decision = False insecure=true [storage] db=elasticsearch endpoint=http://192.168.20.100:9200 If you plan to use a devstack installation on a different machine, update with the correct URIs in the [keystone_authtoken] section Same for the elasticsearch endpoint in the [storage] section 1.4.3 Start API service ----------------------- Quick start the api for test: :: $ freezer-api 192.168.20.100 2. Setup the client machine =========================== :: git clone https://github.com/openstack/freezer.git cd freezer pip install -r requirements.txt python setup.py install 3. Freezer test scenarios ========================= While executing the freezer script it can be useful to monitor the logs: :: tail -f /var/log/freezer.log /var/log/freezer-scheduler.log 3.1 File system tree backup/restore (no snapshot involved) ---------------------------------------------------------- * backup mode: fs * directory * local storage * no lvm 3.1.1 Setup ----------- :: mkdir -p ~/test/data_dir ~/test/data_dir/subdir1 ~/test/data_dir/subdir2 ~/test/data_dir_restore ~/test/storage echo 'alpha bravo' > ~/test/data_dir/file01.txt echo 'charlie delta' > ~/test/data_dir/subdir1/file11.txt ln -s ~/test/data_dir/subdir1/file01.txt ~/test/data_dir/subdir2/link_file01.txt 3.1.2 Backup ------------ :: freezerc --path-to-backup ~/test/data_dir --container ~/test/storage --backup-name my_test_backup --max-level 3 --storage local # add a file echo 'echo foxtrot' > ~/test/data_dir/subdir2/file21.txt # take another backup, level will be 1 freezerc --path-to-backup ~/test/data_dir --container ~/test/storage --backup-name my_test_backup --max-level 3 --storage local 3.1.3 restore ------------- :: freezerc --action restore --restore-abs-path ~/test/data_dir_restore --container ~/test/storage --backup-name copia_dati_fondamentali --storage local 3.2 Backup apache folder using lvm snapshot and restore on a different machine ------------------------------------------------------------------------------ * backup mode: fs * directory * swift storage * lvm snapshot The commands need to be executed with superuser privileges, because of file access rights and also lvm-snapshot creation. We also need the hostname of the source machine to restore on a different machine. :: $ hostname test_machine_1 since we're going to use swift, we also need to source the env vars containing our os credentials 3.2.1 check available space for the lvm snapshot ------------------------------------------------ :: # sudo vgdisplay --- Volume group --- VG Name freezer1-vg System ID Format lvm2 Metadata Areas 1 Metadata Sequence No 13 VG Access read/write VG Status resizable MAX LV 0 Cur LV 2 Open LV 2 Max PV 0 Cur PV 1 Act PV 1 VG Size 49.76 GiB PE Size 4.00 MiB Total PE 12738 Alloc PE / Size 11159 / 43.59 GiB Free PE / Size 1579 / 6.17 GiB VG UUID Ns35jE-eTAT-dy1j-ArWw-8ztM-Wvw2-3nTJOn Here we have 6.17 GB available for lvm snapshots 3.2.2 Backup ------------ Source the env variable containing the OS credentials. The simple script above accepts the OS_tenant and OS_user as parameters :: sudo -s source ~/.venv/bin/activate source os_variables fproject fuser freezerc --action backup --container freezer_test_backups --backup-name apache_backup \ --max-level 3 --max-segment-size 67108864 \ --lvm-auto-snap /etc/apache2 \ --lvm-dirmount /var/freezer/freezer-apache2 \ --lvm-snapsize 1G \ --lvm-snapname freezer-apache2-snap \ --path-to-backup /var/freezer/freezer-apache2/etc/apache2 3.2.3 Restore on a different machine ------------------------------------ We need to use the --restore-from-host parameter because we are restoring on another machine :: sudo -s source ~/.venv/bin/activate source os_variables fproject fuser freezerc --action restore --container freezer_test_backups --backup-name apache_backup \ --restore-abs-path /etc/apache2 \ --restore-from-host test_machine_1 3.3 Use a INI config file to backup directory /etc/ssl ------------------------------------------------------ 3.3.1 Execute a backup using a config file ------------------------------------------ :: cat > backup_apache.ini [job] action=backup container=freezer_test_backups backup+name=apache_backup max_level=3 max_segment_size=67108864 lvm_auto-snap=/etc/apache2 lvm_dirmount=/var/freezer/freezer-apache2 lvm_snapsize=1G lvm_snapname=freezer-apache2-snap path_to_backup=/var/freezer/freezer-apache2/etc/apache2 freezerc --config backup_apache.ini 3.3.2 Execute a restore using a config file ------------------------------------------- :: cat > restore_apache.ini [job] action=restore container=freezer_test_backups backup_name=apache_backup restore_abs_path=/etc/apache2 restore_from_host=test_machine_1 freezerc --config restore_apache.ini 3.4 Incremental backup and restore of mysql using the freezer-scheduler ----------------------------------------------------------------------- We want to push jobs to be executed on the test machine. For that we need to know what is the client_id of the machine we want to execute the jobs on. When not provided with a client_id parameter, the scheduler uses the default value :: client_id = _ For example, if the tenant_id is 03a81f73595c46b38e0cabf047cb0206 and the host running the scheduler is "pluto" the default client_id will be 03a81f73595c46b38e0cabf047cb0206_pluto: :: # openstack project list +----------------------------------+--------------------+ | ID | Name | +----------------------------------+--------------------+ | 03a81f73595c46b38e0cabf047cb0206 | fproject | ..... # hostname pluto # freezer-scheduler client-list +-------------------------------------------+----------------------------+-------------+ | client_id | hostname | description | +-------------------------------------------+----------------------------+-------------+ | 03a81f73595c46b38e0cabf047cb0206_pluto | pluto | | ..... We are going to use "client_node_1" as a client_id. We are therefore going to start the scheduler using the parameter :: -c client_node_1 We also use that parameter when using the freezer-scheduler to interact with the api. 3.4.1 Start the freezer scheduler on the target client machine -------------------------------------------------------------- Start the scheduler with the custom client_id. The scheduler connects to the freezer api service registered in keystone. If there's no api service registered you need to specify it using the command line option --os-endpoint Since this is a demo, we want the freezer-scheduler to poll the api every 10 seconds instead of the default 60 seconds, so we use the parameter "-i 10". :: sudo -s source ~/.venv/bin/activate source os_variables fproject fuser freezer-scheduler -c client_node_1 -i 10 start You can check that the demo in running with: :: # freezer-scheduler status Running with pid: 9972 Then we clean the /var/lib/mysql folder and leave a terminal open with the freezer-scheduler logs: :: rm -rf /var/lib/mysql/* tail -f /var/log/freezer-scheduler.log 3.4.2 Create the job configuration and upload it to the api service ------------------------------------------------------------------- Log in any machine and create the restore job. Remember to source the OS variables and use the custom client_id :: source os_variables fproject fuser cat > job-backup-mysql.conf { "job_actions": [ { "freezer_action": { "mode" : "mysql", "mysql_conf" : "/etc/mysql/debian.cnf", "path_to_backup": "/var/freezer/freezer-db-mysql/var/lib/mysql/", "lvm_auto_snap": "/var/lib/mysql", "lvm_dirmount": "/var/freezer/freezer-db-mysql", "lvm_snapsize": "1G", "backup_name": "freezer-db-mysql", "max_level": 6, "lvm_snapname": "freezer_db-mysql-snap", "max_priority": true, "remove_older_than": 90, "max_segment_size": 67108864, "container": "freezer_backup_devstack_1" }, "max_retries": 3, "max_retries_interval": 10, "mandatory": true } ], "job_schedule" : { }, "description": "mysql backup" } If we want the backup to be executed every day at 3am, we can specify the following scheduling properties: :: "job_schedule" : { "schedule_interval": "1 days", "schedule_start_date": "2015-06-30T03:00:00" }, Upload it into the api using the correct client_id :: freezer-scheduler job-create -c client_node_1 --file job-backup-mysql.conf The status of the jobs can be checked with :: freezer-scheduler -c client_node_1 job-list If no scheduling information is provided, the job will be executed as soon as possible, so its status will go into "running" state, then "completed". Information about the scheduling and backup-execution can be found in /var/log/freezer-scheduler.log and /var/log/freezer.log, respectively. **NOTE**: Recurring jobs never go into "completed" state, as they go back into "scheduled" state. 3.4.3 Create a restore job and push it into the api --------------------------------------------------- If we want to restore on a different node, we need to provide the restore_from_host parameter. :: cat > job-restore-mysql.conf { "job_actions": [ { "freezer_action": { "action": "restore", "restore_abs_path": "/var/lib/mysql", "restore_from_host": "test_machine_1", "backup_name": "freezer-db-mysql", "container": "freezer_backup_devstack_1" }, "max_retries": 1, "max_retries_interval": 10, "mandatory": true } ], "description": "mysql test restore" } freezer-scheduler job-create -c client_node_1 --file job-restore-mysql.conf 3.5 Differential backup and restore ----------------------------------- The difference is in the use of the parameter "always_level": 1 We also specify a different container, so it's easier to spot the files created in the swift container: :: swift list freezer_backup_devstack_1_alwayslevel 3.5.1 Backup job ---------------- :: cat > job-backup.conf { "job_actions": [ { "freezer_action": { "mode" : "mysql", "mysql_conf" : "/etc/mysql/debian.cnf", "path_to_backup": "/var/freezer/freezer-db-mysql/var/lib/mysql/", "lvm_auto_snap": "/var/lib/mysql", "lvm_dirmount": "/var/freezer/freezer-db-mysql", "lvm_snapsize": "1G", "backup_name": "freezer-db-mysql", "always_level": 1, "lvm_snapname": "freezer_db-mysql-snap", "max_priority": true, "remove_older_than": 90, "max_segment_size": 67108864, "container": "freezer_backup_devstack_1_alwayslevel" }, "max_retries": 3, "max_retries_interval": 10, "mandatory": true } ], "job_schedule" : { }, "description": "mysql backup" } freezer-scheduler job-create -c client_node_1 --file job-backup.conf 3.5.2 Restore job ----------------- The restore job is the same as in 3.4.3 :: cat > job-restore.conf { "job_actions": [ { "freezer_action": { "action": "restore", "restore_abs_path": "/var/lib/mysql", "restore_from_host": "test_machine_1", "backup_name": "freezer-db-mysql", "container": "freezer_backup_devstack_1_alwayslevel" }, "max_retries": 1, "max_retries_interval": 10, "mandatory": true } ], "description": "mysql test restore" } freezer-scheduler job-create -c client_node_1 --file job-restore.conf 4. Automated Integration Tests ============================== Automated integration tests are being provided in the directory freezer/tests/integration directory Since they require external resources - such as swift or ssh storage - they are executed only when some environment variables are defined. 4.1 local storage tests ----------------------- always executed automatically, using temporary local directories under /tmp (or whatever temporary path is available) 4.2 ssh storage --------------- SSH storage need the following environment variables to be defined: :: * FREEZER_TEST_SSH_KEY * FREEZER_TEST_SSH_USERNAME * FREEZER_TEST_SSH_HOST * FREEZER_TEST_CONTAINER For example: :: export FREEZER_TEST_SSH_KEY=/home/myuser/.ssh/id_rsa export FREEZER_TEST_SSH_USERNAME=myuser export FREEZER_TEST_SSH_HOST=127.0.0.1 export FREEZER_TEST_CONTAINER=/home/myuser/freezer_test_backup_storage_ssh 4.3 swift storage ----------------- To enable the swift integration tests - besides having a working swift node - the following variables need to be defined accordingly: :: * FREEZER_TEST_OS_TENANT_NAME * FREEZER_TEST_OS_USERNAME * FREEZER_TEST_OS_REGION_NAME * FREEZER_TEST_OS_PASSWORD * FREEZER_TEST_OS_AUTH_URL For example: :: export FREEZER_TEST_OS_TENANT_NAME=fproject export FREEZER_TEST_OS_USERNAME=fuser export FREEZER_TEST_OS_REGION_NAME=RegionOne export FREEZER_TEST_OS_PASSWORD=freezer export FREEZER_TEST_OS_AUTH_URL=http://192.168.56.223:5000/v2.0 The cloud user/tenant has to be already been created 4.4 LVM and MySQL ----------------- Some tests, like LVM snapshots and access to privileged files, need the tests to be executed with superuser privileges. Tests involving such requirements are not executed when run with normal-user privileges. In cases where LVM snapshot capability is not available (for example the filesystem does not make use of LV or there are not enough space available) the LVM tests can be skipped by defining the following env variable: :: * FREEZER_TEST_NO_LVM