| DAS Backup and Recovery - GF v2 level features 1.2. Name(s) and e-mail address of Document Author(s)/Supplier Name: chris.kasso@oracle.com 1.3. Date of This Document: 05/21/2010 (updated 05/27/2010) 2. Project Summary 2.1. Project Description: Provide (reintroduce) the basic v2 level DAS backup and recovery support. 2.2. Risks and Assumptions: The primary contributor to this feature is new to the project and maintains multiple responsibilities. Estimating the time required to implement this set of features is difficult. 3. Problem Summary 3.1. Problem Area: Provide a means for users to backup a DAS instance and recover that instance should it be required. 3.2. Justification: Feature parity with GlassFish Vv2. 4. Technical Description: 4.1. Details: A description of the features can be found in the DAS Backup and Recovery wiki - feature overview. The basic backup and recovery work offered in GFv2 must be offered in GF 3.1 as part of the core product. Notes about existing v2 behavior:
- 4.1.1. A backup or restore can only be executed when the DAS is not running:
aha: ./asadmin backup-domain domain1
Usage: backup-domain [--domaindir domain_directory] [--description description] [--echo=false] [--terse=false] [--verbose=false] [domain_name]
The domain must be stopped before a backup-domain can be performed.
- 4.1.2. By default the backup is stored in the domain directory:
aha: ./asadmin backup-domain domain1
Successfully backed up the domain
Description: 1274993402068
Backup Filename: /work2/gfv2/domains/domain1/backups/sjsas_backup_v00001.zip
Date and time backup was performed: Thu May 27 13:50:02 PDT 2010
Domains Directory: /work2/gfv2/domains
Domain Directory: /work2/gfv2/domains/domain1
Domain Name: domain1
Name of the user that performed the backup: kasso
- 4.1.3. The user can not control the name or location of the backup file. The backup files uses sjsas as part of the backup name.
- 4.1.4. Subsequent backups of the same domain do not overwrite the prior backup.
aha: ./asadmin backup-domain
Successfully backed up the domain
Description: 1274993439377
Backup Filename: /work2/gfv2/domains/domain1/backups/sjsas_backup_v00002.zip
Date and time backup was performed: Thu May 27 13:50:39 PDT 2010
Domains Directory: /work2/gfv2/domains
Domain Directory: /work2/gfv2/domains/domain1
Domain Name: domain1
Name of the user that performed the backup: kasso
- 4.1.5. The output of list-backups displays information about the known backups for an existing domain. This fails if more than one domain exists and a domain name was not provided.
aha: ./asadmin list-backups
Description: 1274993439377
Backup Filename: /work2/gfv2/domains/domain1/backups/sjsas_backup_v00002.zip
Date and time backup was performed: Thu May 27 13:50:39 PDT 2010
Domains Directory: /work2/gfv2/domains
Domain Directory: /work2/gfv2/domains/domain1
Domain Name: domain1
Name of the user that performed the backup: kasso
Description: 1274993402068
Backup Filename: /work2/gfv2/domains/domain1/backups/sjsas_backup_v00001.zip
Date and time backup was performed: Thu May 27 13:50:02 PDT 2010
Domains Directory: /work2/gfv2/domains
Domain Directory: /work2/gfv2/domains/domain1
Domain Name: domain1
Name of the user that performed the backup: kasso
- 4.1.6. If the user does not provide a description (--description) a timestamp in milliseconds is recorded in the Description field.
- 4.1.7. The created zip file will copy all files in the domain directory (including log files but not existing backup files).
- 4.1.8. The backup command will add a backup.properties files to the top of the zip directory hierarchy:
aha: cat backup.properties
#Backup Status
#Thu May 27 13:50:02 PDT 2010
timestamp.human=Thu May 27 13\:50\:02 PDT 2010
domain.name=domain1
user.name=kasso
domain.dir=/work2/gfv2/domains/domain1
domains.dir=/work2/gfv2/domains
timestamp.msec=1274993402068
description=1274993402068
backup.file=/work2/gfv2/domains/domain1/backups/sjsas_backup_v00001.zip
- 4.1.9. The top of the zip file hierarchy looks like this:
aha: ls
addons docroot logs
applications generated master-password
autodeploy imq session-store
backup.properties java-web-start
bin jbi
config lib
- 4.1.10. If only one domain exists a restore-domain request where no domain name is provided as a param will restore the latest backup file (zip) from that domain. If more than one domain exists this command will fail unless the domain name is provided as a command line parameter.
aha: ./asadmin restore-domain
Successfully restored the domain, domain1, to /work2/gfv2/domains/domain1
Description: 1274993439377
Backup Filename: /work2/gfv2/domains/domain1/backups/sjsas_backup_v00002.zip
Date and time backup was performed: Thu May 27 13:50:39 PDT 2010
Domains Directory: /work2/gfv2/domains
Domain Directory: /work2/gfv2/domains/domain1
Domain Name: domain1
Name of the user that performed the backup: kasso
- 4.1.11. If a single domain exists and I use the --filename option to point to a specific backup the backup will be restored to that domain regardless of whether the backed up domain name matches the target domain (A warning is generated). Note if no domain name is supplied and only one domain exists it will restore to that domain by default.
./asadmin restore-domain --filename /work2/gfv2/domains/domain1/backups/sjsas_backup_v00002.zip domain3
WARNING: The original backed-up domain name is [domain1], and you are restoring it to [domain3].
Successfully restored the domain, domain3, to /work2/gfv2/domains/domain3
Description: 1275071906538
Backup Filename: /work2/gfv2/domains/domain1/backups/sjsas_backup_v00001.zip
Date and time backup was performed: Fri May 28 11:38:26 PDT 2010
Domains Directory: /work2/gfv2/domains
Domain Directory: /work2/gfv2/domains/domain1
Domain Name: domain1
Name of the user that performed the backup: kasso
- 4.1.12. If I specify a pointer to the zip file but don't supply a domain name it fails if no domains exist in the domains directory. (Since we know the domain name from the zip why not restore the domain to its original name? Issue 5684)
- 4.1.13. If more than one domain exists in the domain directory and a domain name was not supplied to the restore-domain command the restore fails:
./asadmin restore-domain --filename /work2/gfv2/foobar/backups/sjsas_backup_v00002.zip
Usage: restore-domain [--domaindir domain_directory] [--filename backup_filename] [--description description] [--terse=false] [--echo=false] [--verbose=false] [domain_name]
com.sun.enterprise.cli.framework.CommandException: There is more than one domain in /work2/gfv2/domains. Please use operand to specify the domain.
- 4.1.14. If the domain name is supplied the domain is restored using that name (ignoring other domains which may already exist).
Enhancements for 3.1 (Open Source Edition)
Restoring to a domain which does not match the domain name in the backup is an error. Allow the user to override the error with a new --force option. (This is incompatible with v2 behavior but arguably the v2 behavior was a bug)
./asadmin restore-domain --filename /work2/gfv2/foobar/backups/sjsas_backup_v00002.zip mydomain
ERROR: The target domain name does not match the domain name in the backup. Use --force to restore to a different domain name.
If the domain name specified in the archive does not match any existing domains then the archive should be restored to the name stored in the archive. (Issue 5684)
aha: ./asadmin restore-domain --filename /work2/gfv2/foobar/backups/sjsas_backup_v00002.zip domain1
Successfully restored the domain, domain1, to /work2/gfv2/domains/domain1
Description: 1274993439377
Backup Filename: /work2/gfv2/foobar/backups/sjsas_backup_v00002.zip
Date and time backup was performed: Thu May 27 13:50:39 PDT 2010
Domains Directory: /work2/gfv2/domains
Domain Directory: /work2/gfv2/domains/domain1
Domain Name: domain1
Name of the user that performed the backup: kasso
4.1.17. restore-domain If domain_name is not supplied as a parameter to restore-domain the domain should be restored only if a single domain exists and the domain name matches the archived domain name. Otherwise it is an error. Use --force to override. The v2 behavior is that it will restore to any single domain found in the domains directory (regardless of name) or it will fail to restore any domains. 4.1.18. backup-domain Provide a mechanism to backup to a directory outside of the domain directory. Introduce --backupdir to backup-domain and list-backups.
aha: ./asadmin --backupdir /home/kasso/backups backup-domain
Successfully backed up the domain
Description: 1274993439377
Backup Filename: /home/kasso/backups/domain1_2010_05_28_000001.zip
...
4.1.19. Archive Name Change the archive file name to domain_name_YYYY_MM_DD_NNNNN.zip (from sjsas_backup_vNNNNN.zip). For example: domain1_2010_05_28_000001.zip 4.1.20. Version Property Add a new version property to the backup.properties file. This records the version of GF the backup was created from. 4.1.21. Default Description If a description is not provided provide the following default description: "domain_name backup created on date by user. 4.1.22. list-backups Add --backupdir to list-backups. List backups for the specified domain from the supplied backup directory. List all backups if domain_name is not supplied. 4.2.23. Remove --description from list-backups and restore-backups TBD: pending review by the compatibility team. 4.1.24. delete-backups The details for this command have not be determined yet. This feature will not be implemented in 3.1. 4.1.25. Remove the --description option from command help for list-backups and restore-domain In 2.1 --description was listed as a supported option for list-backups and restore-domain yet when you used that option it produced an error (list-backups) or was a no-op (restore-domain):
aha: ./asadmin list-backups --description alsjflasjdfklajsdlfjaslkfjasd
Usage: list-backups [--domaindir domain_directory] [--terse=false] [--echo=false] [--verbose=false] [domain_name]
CLI013 Option description does not apply to list-backups.
The help for the list-backups and restore-domain should not list --description as a supported parameter. An error should continue to be generated if this parameter is supplied with the list-backups command. If the parameter is supplied as part of the restore-domain it should continue to be a no-op. 4.1.26. Add support for --long/-l options In order to conform with the new asadmin CLI guidelines the --long/-l options will now be supported. They provide the same output as the --verbose option. The --verbose option is still supported but hidden from the --help output. 4.2. Bug/RFE Number(s): 5776: V3 issue which requested DAS recovery to be disabled. 12070: 3.1 feature tracking issue 4.3. In Scope: Basic DAS backup and recover support (similar to GF v2 functionality). 4.4. Out of Scope: More sophisticated backup and recovery support. 4.5. Interfaces: 4.5.1 Public Interfaces List new, public interfaces this project exports.
- Interface: TBD: location and format of the backup zip file.
- Comment:
4.5.2 Private Interfaces List private interfaces which are externally observable.
4.5.3 Deprecated/Removed Interfaces: None. 4.6. Doc Impact: The GF v2 documentation regarding the cli options should be restored to the 3.1 doc set. 4.7. Admin/Config Impact: No config/admin impact.
No out of the box configuration will be required. 4.8. HA Impact: This functionality should have no impact on HA or clustering. 4.9. I18N/L10N Impact: This project may impact L10N. The reintroduced CLI may have strings which need to be re-localized. The restored v2 docs may need localization. 4.10. Packaging, Delivery & Upgrade: 4.10.1. Packaging The functionality should be delivered with the core GF product. No special packaging is required. It should be possible to use an existing package. 4.10.2. Delivery No impact. 4.10.3. Upgrade and Migration: This project does not add any new requirements for update or upgrade. 4.11. Security Impact: No security impact. 4.12. Compatibility Impact No compatibility impact. 4.13. Dependencies: 4.13.1 Internal Dependencies None 4.13.2 External Dependencies None 4.14. Testing Impact: The existing unit tests will be ported to 3.1. See DAS Backup and Recover Milestone Schedule
|
