current-api.h

   1 /*
   2  * A Proxmox Backup Server C interface, intended for use inside Qemu
   3  *
   4  * Copyright (C) 2019 Proxmox Server Solutions GmbH
   5  *
   6  * Authors:
   7  *  Dietmar Maurer (dietmar@proxmox.com)
   8  *
   9  * This work is licensed under the terms of the GNU GPL, version 2 or later.
  10  *
  11  *
  12  * NOTE: Async Commands
  13  *
  14  * Most commands are asynchronous (marked as _async). They run in a
  15  * separate thread and have the following parameters:
  16  *
  17  * callback: extern "C" fn(*mut c_void),
  18  * callback_data: *mut c_void,
  19  * result: *mut c_int,
  20  * error: *mut *mut c_char,
  21  *
  22  * The callback function is called when the the async function is
  23  * ready. Possible errors are returned in 'error'.
  24  */
  25
  26
  27 #ifndef PROXMOX_BACKUP_QEMU_H
  28 #define PROXMOX_BACKUP_QEMU_H
  29
  30 #include <stdarg.h>
  31 #include <stdbool.h>
  32 #include <stdint.h>
  33 #include <stdlib.h>
  34
  35 #define PROXMOX_BACKUP_DEFAULT_CHUNK_SIZE ((1024 * 1024) * 4)
  36
  37 /**
  38  * Opaque handle for backups jobs
  39  */
  40 typedef struct ProxmoxBackupHandle {
  41
  42 } ProxmoxBackupHandle;
  43
  44 /**
  45  * Opaque handle for restore jobs
  46  */
  47 typedef struct ProxmoxRestoreHandle {
  48
  49 } ProxmoxRestoreHandle;
  50
  51 /**
  52  * Return a read-only pointer to a string containing the version of the library.
  53  */
  54 const char *proxmox_backup_qemu_version(void);
  55
  56 /**
  57  * Free returned error messages
  58  *
  59  * All calls can return error messages, but they are allocated using
  60  * the rust standard library. This call moves ownership back to rust
  61  * and free the allocated memory.
  62  */
  63 void proxmox_backup_free_error(char *ptr);
  64
  65 /**
  66  * Returns the text presentation (relative path) for a backup snapshot
  67  *
  68  * The resturned value is allocated with strdup(), and can be freed
  69  * with free().
  70  */
  71 const char *proxmox_backup_snapshot_string(const char *backup_type,
  72                                            const char *backup_id,
  73                                            int64_t backup_time,
  74                                            char **error);
  75
  76 /**
  77  * Create a new instance
  78  *
  79  * Uses `PROXMOX_BACKUP_DEFAULT_CHUNK_SIZE` if `chunk_size` is zero.
  80  */
  81 struct ProxmoxBackupHandle *proxmox_backup_new(const char *repo,
  82                                                const char *backup_id,
  83                                                uint64_t backup_time,
  84                                                uint64_t chunk_size,
  85                                                const char *password,
  86                                                const char *keyfile,
  87                                                const char *key_password,
  88                                                const char *master_keyfile,
  89                                                bool compress,
  90                                                bool encrypt,
  91                                                const char *fingerprint,
  92                                                char **error);
  93
  94 /**
  95  * Open connection to the backup server (sync)
  96  *
  97  * Returns:
  98  *  0 ... Sucecss (no prevbious backup)
  99  *  1 ... Success (found previous backup)
 100  * -1 ... Error
 101  */
 102 int proxmox_backup_connect(struct ProxmoxBackupHandle *handle, char **error);
 103
 104 /**
 105  * Open connection to the backup server
 106  *
 107  * Returns:
 108  *  0 ... Sucecss (no prevbious backup)
 109  *  1 ... Success (found previous backup)
 110  * -1 ... Error
 111  */
 112 void proxmox_backup_connect_async(struct ProxmoxBackupHandle *handle,
 113                                   void (*callback)(void*),
 114                                   void *callback_data,
 115                                   int *result,
 116                                   char **error);
 117
 118 /**
 119  * Abort a running backup task
 120  *
 121  * This stops the current backup task. It is still necessary to call
 122  * proxmox_backup_disconnect() to close the connection and free
 123  * allocated memory.
 124  */
 125 void proxmox_backup_abort(struct ProxmoxBackupHandle *handle, const char *reason);
 126
 127 /**
 128  * Check if we can do incremental backups.
 129  *
 130  * This method compares the csum from last backup manifest with the
 131  * checksum stored locally.
 132  */
 133 int proxmox_backup_check_incremental(struct ProxmoxBackupHandle *handle,
 134                                      const char *device_name,
 135                                      uint64_t size);
 136
 137 /**
 138  * Register a backup image (sync)
 139  */
 140 int proxmox_backup_register_image(struct ProxmoxBackupHandle *handle,
 141                                   const char *device_name,
 142                                   uint64_t size,
 143                                   bool incremental,
 144                                   char **error);
 145
 146 /**
 147  * Register a backup image
 148  *
 149  * Create a new image archive on the backup server
 150  * ('<device_name>.img.fidx'). The returned integer is the dev_id
 151  * parameter for the proxmox_backup_write_data_async() method.
 152  */
 153 void proxmox_backup_register_image_async(struct ProxmoxBackupHandle *handle,
 154                                          const char *device_name,
 155                                          uint64_t size,
 156                                          bool incremental,
 157                                          void (*callback)(void*),
 158                                          void *callback_data,
 159                                          int *result,
 160                                          char **error);
 161
 162 /**
 163  * Add a configuration blob to the backup (sync)
 164  */
 165 int proxmox_backup_add_config(struct ProxmoxBackupHandle *handle,
 166                               const char *name,
 167                               const uint8_t *data,
 168                               uint64_t size,
 169                               char **error);
 170
 171 /**
 172  * Add a configuration blob to the backup
 173  *
 174  * Create and upload a data blob "<name>.blob".
 175  */
 176 void proxmox_backup_add_config_async(struct ProxmoxBackupHandle *handle,
 177                                      const char *name,
 178                                      const uint8_t *data,
 179                                      uint64_t size,
 180                                      void (*callback)(void*),
 181                                      void *callback_data,
 182                                      int *result,
 183                                      char **error);
 184
 185 /**
 186  * Write data to into a registered image (sync)
 187  *
 188  * Upload a chunk of data for the <dev_id> image.
 189  *
 190  * The data pointer may be NULL in order to write the zero chunk
 191  * (only allowed if size == chunk_size)
 192  *
 193  * Returns:
 194  * -1: on error
 195  *  0: successful, chunk already exists on server, so it was resued
 196  *  size: successful, chunk uploaded
 197  */
 198 int proxmox_backup_write_data(struct ProxmoxBackupHandle *handle,
 199                               uint8_t dev_id,
 200                               const uint8_t *data,
 201                               uint64_t offset,
 202                               uint64_t size,
 203                               char **error);
 204
 205 /**
 206  * Write data to into a registered image
 207  *
 208  * Upload a chunk of data for the <dev_id> image.
 209  *
 210  * The data pointer may be NULL in order to write the zero chunk
 211  * (only allowed if size == chunk_size)
 212  *
 213  * Note: The data pointer needs to be valid until the async
 214  * opteration is finished.
 215  *
 216  * Returns:
 217  * -1: on error
 218  *  0: successful, chunk already exists on server, so it was resued
 219  *  size: successful, chunk uploaded
 220  */
 221 void proxmox_backup_write_data_async(struct ProxmoxBackupHandle *handle,
 222                                      uint8_t dev_id,
 223                                      const uint8_t *data,
 224                                      uint64_t offset,
 225                                      uint64_t size,
 226                                      void (*callback)(void*),
 227                                      void *callback_data,
 228                                      int *result,
 229                                      char **error);
 230
 231 /**
 232  * Close a registered image (sync)
 233  */
 234 int proxmox_backup_close_image(struct ProxmoxBackupHandle *handle, uint8_t dev_id, char **error);
 235
 236 /**
 237  * Close a registered image
 238  *
 239  * Mark the image as closed. Further writes are not possible.
 240  */
 241 void proxmox_backup_close_image_async(struct ProxmoxBackupHandle *handle,
 242                                       uint8_t dev_id,
 243                                       void (*callback)(void*),
 244                                       void *callback_data,
 245                                       int *result,
 246                                       char **error);
 247
 248 /**
 249  * Finish the backup (sync)
 250  */
 251 int proxmox_backup_finish(struct ProxmoxBackupHandle *handle, char **error);
 252
 253 /**
 254  * Finish the backup
 255  *
 256  * Finish the backup by creating and uploading the backup manifest.
 257  * All registered images have to be closed before calling this.
 258  */
 259 void proxmox_backup_finish_async(struct ProxmoxBackupHandle *handle,
 260                                  void (*callback)(void*),
 261                                  void *callback_data,
 262                                  int *result,
 263                                  char **error);
 264
 265 /**
 266  * Disconnect and free allocated memory
 267  *
 268  * The handle becomes invalid after this call.
 269  */
 270 void proxmox_backup_disconnect(struct ProxmoxBackupHandle *handle);
 271
 272 /**
 273  * Connect the the backup server for restore (sync)
 274  */
 275 struct ProxmoxRestoreHandle *proxmox_restore_new(const char *repo,
 276                                                  const char *snapshot,
 277                                                  const char *password,
 278                                                  const char *keyfile,
 279                                                  const char *key_password,
 280                                                  const char *fingerprint,
 281                                                  char **error);
 282
 283 /**
 284  * Open connection to the backup server (sync)
 285  *
 286  * Returns:
 287  *  0 ... Sucecss (no prevbious backup)
 288  * -1 ... Error
 289  */
 290 int proxmox_restore_connect(struct ProxmoxRestoreHandle *handle, char **error);
 291
 292 /**
 293  * Open connection to the backup server (async)
 294  *
 295  * Returns:
 296  *  0 ... Sucecss (no prevbious backup)
 297  * -1 ... Error
 298  */
 299 void proxmox_restore_connect_async(struct ProxmoxRestoreHandle *handle,
 300                                    void (*callback)(void*),
 301                                    void *callback_data,
 302                                    int *result,
 303                                    char **error);
 304
 305 /**
 306  * Disconnect and free allocated memory
 307  *
 308  * The handle becomes invalid after this call.
 309  */
 310 void proxmox_restore_disconnect(struct ProxmoxRestoreHandle *handle);
 311
 312 /**
 313  * Restore an image (sync)
 314  *
 315  * Image data is downloaded and sequentially dumped to the callback.
 316  */
 317 int proxmox_restore_image(struct ProxmoxRestoreHandle *handle,
 318                           const char *archive_name,
 319                           int (*callback)(void*, uint64_t, const unsigned char*, uint64_t),
 320                           void *callback_data,
 321                           char **error,
 322                           bool verbose);
 323
 324 /**
 325  * Retrieve the ID of a handle used to access data in the given archive (sync)
 326  */
 327 int proxmox_restore_open_image(struct ProxmoxRestoreHandle *handle,
 328                                const char *archive_name,
 329                                char **error);
 330
 331 /**
 332  * Retrieve the ID of a handle used to access data in the given archive (async)
 333  */
 334 void proxmox_restore_open_image_async(struct ProxmoxRestoreHandle *handle,
 335                                       const char *archive_name,
 336                                       void (*callback)(void*),
 337                                       void *callback_data,
 338                                       int *result,
 339                                       char **error);
 340
 341 /**
 342  * Retrieve the length of a given archive handle in bytes
 343  */
 344 long proxmox_restore_get_image_length(struct ProxmoxRestoreHandle *handle,
 345                                       uint8_t aid,
 346                                       char **error);
 347
 348 /**
 349  * Read data from the backup image at the given offset (sync)
 350  *
 351  * Reads up to size bytes from handle aid at offset. On success,
 352  * returns the number of bytes read. (a return of zero indicates end
 353  * of file).
 354  *
 355  * Note: It is not an error for a successful call to transfer fewer
 356  * bytes than requested.
 357  */
 358 int proxmox_restore_read_image_at(struct ProxmoxRestoreHandle *handle,
 359                                   uint8_t aid,
 360                                   uint8_t *data,
 361                                   uint64_t offset,
 362                                   uint64_t size,
 363                                   char **error);
 364
 365 /**
 366  * Read data from the backup image at the given offset (async)
 367  *
 368  * Reads up to size bytes from handle aid at offset. On success,
 369  * returns the number of bytes read. (a return of zero indicates end
 370  * of file).
 371  *
 372  * Note: The data pointer needs to be valid until the async
 373  * opteration is finished.
 374  *
 375  * Note: The call will only ever transfer less than 'size' bytes if
 376  * the end of the file has been reached.
 377  */
 378 void proxmox_restore_read_image_at_async(struct ProxmoxRestoreHandle *handle,
 379                                          uint8_t aid,
 380                                          uint8_t *data,
 381                                          uint64_t offset,
 382                                          uint64_t size,
 383                                          void (*callback)(void*),
 384                                          void *callback_data,
 385                                          int *result,
 386                                          char **error);
 387
 388 /**
 389  * Serialize all state data into a byte buffer. Can be loaded again with
 390  * proxmox_import_state. Use for migration for example.
 391  *
 392  * Length of the returned buffer is written to buf_size. Returned buffer must
 393  * be freed with proxmox_free_state_buf.
 394  */
 395 uint8_t *proxmox_export_state(uintptr_t *buf_size);
 396
 397 /**
 398  * Load state serialized by proxmox_export_state. If loading fails, a message
 399  * will be logged to stderr, but the function will not fail.
 400  */
 401 void proxmox_import_state(const uint8_t *buf, uintptr_t buf_size);
 402
 403 /**
 404  * Free a buffer acquired from proxmox_export_state.
 405  */
 406 void proxmox_free_state_buf(uint8_t *buf);
 407
 408 #endif /* PROXMOX_BACKUP_QEMU_H */