2010-05-14 01:05:28 +04:00
/* -------------------------------------------------------------------------- */
2022-04-07 20:49:58 +03:00
/* Copyright 2002-2022, OpenNebula Project, OpenNebula Systems */
2010-05-14 01:05:28 +04:00
/* */
/* Licensed under the Apache License, Version 2.0 (the "License"); you may */
/* not use this file except in compliance with the License. You may obtain */
/* a copy of the License at */
/* */
/* http://www.apache.org/licenses/LICENSE-2.0 */
/* */
/* Unless required by applicable law or agreed to in writing, software */
/* distributed under the License is distributed on an "AS IS" BASIS, */
/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. */
/* See the License for the specific language governing permissions and */
/* limitations under the License. */
/* -------------------------------------------------------------------------- */
# ifndef OBJECT_XML_H_
# define OBJECT_XML_H_
# include <string>
# include <vector>
2016-01-08 03:06:26 +03:00
# include <sstream>
2010-05-14 01:05:28 +04:00
# include <libxml/tree.h>
# include <libxml/parser.h>
# include <libxml/xpath.h>
# include <libxml/xpathInternals.h>
/**
* This class represents a generic Object supported by a xml document .
* The class provides basic methods to query attributes , and get xml nodes
*/
class ObjectXML
{
public :
// ---------------------- Constructors ------------------------------------
2019-09-03 17:31:51 +03:00
ObjectXML ( ) : xml ( 0 ) , ctx ( 0 ) { }
2010-05-14 01:05:28 +04:00
/**
* Constructs an object using a XML document
*/
2016-01-08 03:06:26 +03:00
ObjectXML ( const std : : string & xml_doc ) ;
2010-05-14 01:05:28 +04:00
/**
* Constructs an object using a XML Node . The node is copied to the new
* object
*/
ObjectXML ( const xmlNodePtr node ) ;
virtual ~ ObjectXML ( ) ;
/**
2016-02-05 02:55:24 +03:00
* Gets elements by xpath .
* @ param values vector with the element values .
* @ param expr of the xml element
2010-05-14 01:05:28 +04:00
*/
2016-02-05 02:55:24 +03:00
template < typename T >
void xpaths ( std : : vector < T > & values , const char * expr )
2016-01-08 03:06:26 +03:00
{
2016-02-05 02:55:24 +03:00
xmlXPathObjectPtr obj ;
2011-02-25 15:54:39 +03:00
2016-02-05 02:55:24 +03:00
xmlNodePtr cur ;
xmlChar * str_ptr ;
2019-09-03 17:31:51 +03:00
obj = xmlXPathEvalExpression ( reinterpret_cast < const xmlChar * > ( expr ) , ctx ) ;
2016-02-05 02:55:24 +03:00
if ( obj = = 0 )
{
return ;
}
switch ( obj - > type )
{
case XPATH_NUMBER :
values . push_back ( static_cast < T > ( obj - > floatval ) ) ;
break ;
case XPATH_NODESET :
2020-04-16 16:48:41 +03:00
if ( obj - > nodesetval = = 0 )
{
return ;
}
2019-09-03 17:31:51 +03:00
for ( int i = 0 ; i < obj - > nodesetval - > nodeNr ; + + i )
2016-02-05 02:55:24 +03:00
{
cur = obj - > nodesetval - > nodeTab [ i ] ;
if ( cur = = 0 | | cur - > type ! = XML_ELEMENT_NODE )
{
continue ;
}
str_ptr = xmlNodeGetContent ( cur ) ;
if ( str_ptr ! = 0 )
{
std : : istringstream iss ( reinterpret_cast < char * > ( str_ptr ) ) ;
T val ;
iss > > std : : dec > > val ;
if ( ! iss . fail ( ) )
{
values . push_back ( val ) ;
}
xmlFree ( str_ptr ) ;
}
}
break ;
default :
break ;
}
xmlXPathFreeObject ( obj ) ;
2016-01-08 03:06:26 +03:00
} ;
2011-02-25 15:54:39 +03:00
2016-02-05 02:55:24 +03:00
void xpaths ( std : : vector < std : : string > & values , const char * xpath_expr ) ;
2014-10-30 19:21:27 +03:00
/**
2016-02-05 02:55:24 +03:00
* Gets a xpath attribute , if the attribute is not found a default is used .
* This function only returns the first element
* @ param value of the element
2014-10-30 19:21:27 +03:00
* @ param xpath_expr of the xml element
* @ param def default value if the element is not found
*
* @ return - 1 if default was set
*/
2016-02-05 02:55:24 +03:00
template < typename T >
int xpath ( T & value , const char * xpath_expr , const T & def )
2016-01-08 03:06:26 +03:00
{
2016-02-05 02:55:24 +03:00
std : : vector < std : : string > values ;
2011-03-03 20:53:41 +03:00
2016-02-05 02:55:24 +03:00
xpaths ( values , xpath_expr ) ;
2012-12-04 16:35:45 +04:00
2016-02-05 02:55:24 +03:00
if ( values . empty ( ) = = true )
{
value = def ;
return - 1 ;
}
2012-12-04 16:35:45 +04:00
2016-02-05 02:55:24 +03:00
std : : istringstream iss ( values [ 0 ] ) ;
2016-01-08 03:06:26 +03:00
2016-02-05 02:55:24 +03:00
iss > > std : : dec > > value ;
2016-01-08 03:06:26 +03:00
2016-02-05 02:55:24 +03:00
if ( iss . fail ( ) = = true )
{
value = def ;
return - 1 ;
}
return 0 ;
2016-01-08 03:06:26 +03:00
}
2011-02-25 17:23:46 +03:00
2016-02-05 02:55:24 +03:00
int xpath ( std : : string & value , const char * xpath_expr , const char * def ) ;
2011-02-25 16:17:41 +03:00
/**
* Gets the value of an element from an xml string
* @ param value the value of the element
* @ param xml the xml string
* @ param xpath the xpath of the target element
2013-08-06 19:25:21 +04:00
*
2011-02-25 16:17:41 +03:00
* @ return - 1 if the element was not found
*/
2016-01-08 03:06:26 +03:00
static int xpath_value ( std : : string & value , const char * xml , const char * xpath ) ;
2011-02-25 16:17:41 +03:00
2013-08-06 19:25:21 +04:00
/**
* Search the Object for a given attribute in a set of object specific
* routes .
* @ param name of the attribute
* @ param value of the attribute
*
* @ return - 1 if the element was not found
*/
2016-03-03 17:39:41 +03:00
virtual int search ( const char * name , std : : string & value )
{
return __search ( name , value ) ;
}
2013-08-06 19:25:21 +04:00
2016-03-03 17:39:41 +03:00
virtual int search ( const char * name , int & value )
{
return __search ( name , value ) ;
}
2013-08-06 19:25:21 +04:00
2016-03-03 17:39:41 +03:00
virtual int search ( const char * name , float & value )
{
return __search ( name , value ) ;
}
2013-08-06 19:25:21 +04:00
2016-07-19 13:20:13 +03:00
/**
* Search the Object for a given attribute in a set of object specific
* routes .
* @ param name of the attribute
* @ results vector of attributes that matches the query
*/
template < typename T >
void search ( const char * name , std : : vector < T > & results )
{
if ( name [ 0 ] = = ' / ' )
{
xpaths ( results , name ) ;
}
else if ( num_paths = = 0 )
{
results . clear ( ) ;
}
else
{
std : : ostringstream xpath ;
xpath < < paths [ 0 ] < < name ;
for ( int i = 1 ; i < num_paths ; i + + )
{
xpath < < ' | ' < < paths [ i ] < < name ;
}
xpaths ( results , xpath . str ( ) . c_str ( ) ) ;
}
}
2010-05-14 01:05:28 +04:00
/**
* Get xml nodes by Xpath
* @ param xpath_expr the Xpath for the elements
* @ param content nodes for the given Xpath expression . The nodes are
2016-03-10 18:28:33 +03:00
* returned as pointers to the object nodes .
* @ return the number of nodes found
*/
int get_nodes ( const std : : string & xpath_expr ,
std : : vector < xmlNodePtr > & content ) const ;
2010-05-14 01:05:28 +04:00
F #5516: New backup interface for OpenNebula
co-authored-by: Frederick Borges <fborges@opennebula.io>
co-authored-by: Neal Hansen <nhansen@opennebula.io>
co-authored-by: Daniel Clavijo Coca <dclavijo@opennebula.io>
co-authored-by: Pavel Czerný <pczerny@opennebula.systems>
BACKUP INTERFACE
=================
* Backups are exposed through a a special Datastore (BACKUP_DS) and
Image (BACKUP) types. These new types can only be used for backup'ing
up VMs. This approach allows to:
- Implement tier based backup policies (backups made on different
locations).
- Leverage access control and quota systems
- Support differnt storage and backup technologies
* Backup interface for the VMs:
- VM configures backups with BACKUP_CONFIG. This attribute can be set
in the VM template or updated with updateconf API call. It can include:
+ BACKUP_VOLATILE: To backup or not volatile disks
+ FS_FREEZE: How the FS is freeze for running VMs (qemu-agent,
suspend or none). When possible backups are crash consistent.
+ KEEP_LAST: keep only a given number of backups.
- Backups are initiated by the one.vm.backup API call that requires
the target Datastore to perform the backup (one-shot). This is
exposed by the onevm backup command.
- Backups can be periodic through scheduled actions.
- Backup configuration is updated with one.vm.updateconf API call.
* Restore interface:
- Restores are initiated by the one.image.restore API call. This is
exposed by oneimage restore command.
- Restore include configurable options for the VM template
+ NO_IP: to not preserve IP addresses (but keep the NICs and network
mapping)
+ NO_NIC: to not preserve network mappings
- Other template attributes:
+ Clean PCI devices, including network configuration in case of TYPE=NIC
attributes. By default it removes SHORT_ADDRESS and leave the "auto"
selection attributes.
+ Clean NUMA_NODE, removes node id and cpu sets. It keeps the NUMA node
- It is possible to restore single files stored in the repository by
using the backup specific URL.
* Sunstone (Ruby version) has been updated to expose this feautres.
BACKUP DRIVERS & IMPLEMENTATION
===============================
* Backup operation is implemented by a combination of 3 driver operations:
- VMM. New (internal oned <-> one_vmm_exec.rb) to orchestrate
backups for RUNNING VMs.
- TM. This commit introduces 2 new operations (and their
corresponding _live variants):
+ pre_backup(_live): Prepares the disks to be back'ed up in the
repository. It is specific to the driver: (i) ceph uses the export
operation; (ii) qcow2/raw uses snapshot-create-as and fs_freeze as
needed.
+ post_backup(_live): Performs cleanning operations, i.e. KVM
snapshots or tmp dirs.
- DATASTORE. Each backup technology is represented by its
corresponfing driver, that needs to implement:
+ backup: it takes the VM disks in file (qcow2) format and stores it
the backup repository.
+ restore: it takes a backup image and restores the associated disks
and VM template.
+ monitor: to gather available space in the repository
+ rm: to remove existing backups
+ stat: to return the "restored" size of a disk stored in a backup
+ downloader pseudo-URL handler: in the form
<backup_proto>://<driver_snapshot_id>/<disk filename>
BACKUP MANAGEMENT
=================
Backup actions may potentially take some time, leaving some vmm_exec threads in
use for a long time, stucking other vmm operations. Backups are planned
by the scheduler through the sched action interface.
Two attributes has been added to sched.conf:
* MAX_BACKUPS max active backup operations in the cloud. No more
backups will be started beyond this limit.
* MAX_BACKUPS_HOST max number of backups per host
* Fix onevm CLI to properly show and manage schedule actions. --schedule
supports now, as well as relative times +<seconds_from_stime>
onvm backup --schedule now -d 100 63
* Backup is added as VM_ADMIN_ACTIONS in oned.conf. Regular users needs
to use the batch interface or request specific permissions
Internal restructure of Scheduler:
- All sched_actions interface is now in SchedActionsXML class and files.
This class uses references to VM XML, and MUST be used in the same
lifetime scope.
- XMLRPC API calls for sched actions has been moved to ScheduledActionXML.cc as
static functions.
- VirtualMachineActionPool includes counters for active backups (total
and per host).
SUPPORTED PLATFORMS
====================
* hypervisor: KVM
* TM: qcow2/shared/ssh, ceph
* backup: restic, rsync
Notes on Ceph
* Ceph backups are performed in the following steps:
1. A snapshot of each disk is taken (group snapshots cannot be used as
it seems we cannot export the disks afterwards)
2. Disks are export to a file
3. File is converted to qcow2 format
4. Disk files are upload to the backup repo
TODO:
* Confirm crash consistent snapshots cannot be used in Ceph
TODO:
* Check if using VM dir instead of full path is better to accomodate
DS migrations i.e.:
- Current path: /var/lib/one/datastores/100/53/backup/disk.0
- Proposal: 53/backup/disk.0
RESTIC DRIVER
=============
Developed together with this feature is part of the EE edtion.
* It supports the SFTP protocol, the following attributes are
supported:
- RESTIC_SFTP_SERVER
- RESTIC_SFTP_USER: only if different from oneadmin
- RESTIC_PASSWORD
- RESTIC_IONICE: Run restic under a given ionice priority (class 2)
- RESTIC_NICE: Run restic under a given nice
- RESTIC_BWLIMIT: Limit restic upload/download BW
- RESTIC_COMPRESSION: Restic 0.14 implements compression (three modes:
off, auto, max). This requires repositories version 2. By default,
auto is used (average compression without to much CPU usage)
- RESTIC_CONNECTIONS: Sets the number of concurrent connections to a
backend (5 by default). For high-latency backends this number can be
increased.
* downloader URL: restic://<datastore_id>/<snapshot_id>/<file_name>
snapshot_id is the restic snapshot hash. To recover single disk images
from a backup. This URLs support:
- RESTIC_CONNECTIONS
- RESTIC_BWLIMIT
- RESTIC_IONICE
- RESTIC_NICE
These options needs to be defined in the associated datastore.
RSYNC DRIVER
=============
A rsync driver is included as part of the CE distribution. It uses the
rsync tool to store backups in a remote server through SSH:
* The following attributes are supported to configure the backup
datastore:
- RSYNC_HOST
- RSYNC_USER
- RSYNC_ARGS: Arguments to perform the rsync operatin (-aS by default)
* downloader URL: rsync://<ds_id>/<vmid>/<hash>/<file> can be used to recover
single files from an existing backup. (RSYNC_HOST and RSYN_USER needs
to be set in ds_id
EMULATOR_CPUS
=============
This commit includes a non related backup feature:
* Add EMULATOR_CPUS (KVM). This host (or cluster attribute) defines the
CPU IDs where the emulator threads will be pinned. If this value is
not defined the allocated CPU wll be used when using a PIN policy.
(cherry picked from commit a9e6a8e000e9a5a2f56f80ce622ad9ffc9fa032b)
F OpenNebula/one#5516: adding rsync backup driver
(cherry picked from commit fb52edf5d009dc02b071063afb97c6519b9e8305)
F OpenNebula/one#5516: update install.sh, add vmid to source, some polish
Signed-off-by: Neal Hansen <nhansen@opennebula.io>
(cherry picked from commit 6fc6f8a67e435f7f92d5c40fdc3d1c825ab5581d)
F OpenNebula/one#5516: cleanup
Signed-off-by: Neal Hansen <nhansen@opennebula.io>
(cherry picked from commit 12f4333b833f23098142cd4762eb9e6c505e1340)
F OpenNebula/one#5516: update downloader, default args, size check
Signed-off-by: Neal Hansen <nhansen@opennebula.io>
(cherry picked from commit 510124ef2780a4e2e8c3d128c9a42945be38a305)
LL
(cherry picked from commit d4fcd134dc293f2b862086936db4d552792539fa)
2022-09-09 12:46:44 +03:00
/**
* Count number of nodes matching a given xpath_expr
* @ param xpath_expr the Xpath for the elements
* @ return the number of nodes found
*/
int count_nodes ( const std : : string & xpath_expr ) const ;
2013-01-22 17:14:56 +04:00
/**
* Adds a copy of the node as a child of the node in the xpath expression .
* The source node must be cleaned by the caller .
*
* @ param xpath_expr Path of the parent node
* @ param node Node copy and add
* @ param new_name New name for the node copy
*
* @ return 0 on success , - 1 otherwise
*/
int add_node ( const char * xpath_expr , xmlNodePtr node , const char * new_name ) ;
2020-05-28 17:49:00 +03:00
/**
* Removes nodes from the object by xPath
*
* @ param xpath_expr Path of the parent node
*
* @ return number of elements removed
*/
int remove_nodes ( const char * xpath_expr ) ;
2010-05-14 01:05:28 +04:00
/**
2011-07-03 03:57:39 +04:00
* Frees a vector of XMLNodes , as returned by the get_nodes function
* @ param content the vector of xmlNodePtr
*/
2016-03-10 18:28:33 +03:00
void free_nodes ( std : : vector < xmlNodePtr > & content ) const
2011-07-03 03:57:39 +04:00
{
2020-09-17 12:10:55 +03:00
for ( auto it : content )
2011-07-03 03:57:39 +04:00
{
2020-09-17 12:10:55 +03:00
xmlFreeNode ( it ) ;
2011-07-03 03:57:39 +04:00
}
} ;
/**
2010-05-14 01:05:28 +04:00
* Updates the object representation with a new XML document . Previous
* XML resources are freed
* @ param xml_doc the new xml document
*/
2016-01-08 03:06:26 +03:00
int update_from_str ( const std : : string & xml_doc ) ;
2010-05-14 01:05:28 +04:00
/**
* Updates the object representation with a new XML document . Previous
* XML resources are freed
* @ param xml_doc the new xml document
*/
2011-02-24 20:12:26 +03:00
int update_from_node ( const xmlNodePtr node ) ;
2010-05-14 01:05:28 +04:00
2011-12-19 20:07:32 +04:00
/**
* Validates the xml string
*
* @ param xml_doc string to parse
* @ return 0 if the xml validates
*/
2016-01-08 03:06:26 +03:00
static int validate_xml ( const std : : string & xml_doc ) ;
2011-12-19 20:07:32 +04:00
2020-05-18 03:23:29 +03:00
/**
* Validates the XML doc against a RelaxNG schema
*
* @ param xml_doc string containing the XML document
* @ param schema_path path to RelaxNG schema file
* @ return 0 if the xml validates
*/
static int validate_rng ( const std : : string & xml_doc ,
const std : : string & schema_path ) ;
2013-01-30 20:49:24 +04:00
/**
* Renames the nodes given in the xpath expression
* @ param xpath_expr xpath expression to find the nodes to rename
* @ param new_name new name for the xml elements
*
* @ return the number of nodes renamed
*/
int rename_nodes ( const char * xpath_expr , const char * new_name ) ;
2010-05-14 05:32:42 +04:00
// ---------------------------------------------------------
// Lex & bison parser for requirements and rank expressions
// ---------------------------------------------------------
/**
* Evaluates a requirement expression on the given host .
* @ param requirements string
* @ param result true if the host matches the requirements
* @ param errmsg string describing the error , must be freed by the
* calling function
* @ return 0 on success
*/
2016-01-08 03:06:26 +03:00
int eval_bool ( const std : : string & expr , bool & result , char * * errmsg ) ;
2010-05-14 05:32:42 +04:00
/**
* Evaluates a rank expression on the given host .
* @ param rank string
* @ param result of the rank evaluation
* @ param errmsg string describing the error , must be freed by the
* calling function
* @ return 0 on success
*/
2016-01-08 03:06:26 +03:00
int eval_arith ( const std : : string & expr , int & result , char * * errmsg ) ;
2010-05-14 05:32:42 +04:00
2010-05-14 21:15:20 +04:00
/**
* Function to write the Object in an output stream
*/
2016-01-08 03:06:26 +03:00
friend std : : ostream & operator < < ( std : : ostream & os , ObjectXML & oxml )
2010-05-14 21:15:20 +04:00
{
2017-07-18 19:19:30 +03:00
xmlNodePtr root_node = xmlDocGetRootElement ( oxml . xml ) ;
2010-05-14 21:15:20 +04:00
2017-07-18 19:19:30 +03:00
if ( root_node = = 0 )
{
return os ;
}
xmlBufferPtr buffer = xmlBufferCreate ( ) ;
xmlNodeDump ( buffer , oxml . xml , root_node , 0 , 0 ) ;
2010-05-14 21:15:20 +04:00
2017-07-18 19:19:30 +03:00
std : : string str ( reinterpret_cast < char * > ( buffer - > content ) ) ;
2010-05-14 21:15:20 +04:00
os < < str ;
2017-07-18 19:19:30 +03:00
xmlBufferFree ( buffer ) ;
2010-05-14 21:15:20 +04:00
return os ;
} ;
2013-08-06 19:25:21 +04:00
protected :
/**
* Array of paths to look for attributes in search methods
*/
const char * * paths ;
/**
* Number of elements in paths array
*/
int num_paths ;
2010-05-14 01:05:28 +04:00
private :
/**
* XML representation of the Object
*/
xmlDocPtr xml ;
/**
* XPath Context to access Object elements
*/
xmlXPathContextPtr ctx ;
/**
* Parse a XML documents and initializes XPath contexts
*/
2016-01-08 03:06:26 +03:00
void xml_parse ( const std : : string & xml_doc ) ;
2013-08-06 19:25:21 +04:00
2016-03-03 17:39:41 +03:00
/**
* Search the Object for a given attribute in a set of object specific
* routes .
* @ param name of the attribute
* @ param value of the attribute
*
* @ return - 1 if the element was not found
*/
template < typename T >
int __search ( const char * name , T & value )
{
std : : vector < T > results ;
2016-07-19 13:20:13 +03:00
search ( name , results ) ;
2016-03-03 17:39:41 +03:00
if ( results . size ( ) ! = 0 )
{
value = results [ 0 ] ;
return 0 ;
}
return - 1 ;
} ;
2010-05-14 01:05:28 +04:00
} ;
# endif /*OBJECT_XML_H_*/