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  * DEPRECATED: Create a new instance in the root namespace.
  78  *
  79  * Uses `PROXMOX_BACKUP_DEFAULT_CHUNK_SIZE` if `chunk_size` is zero.
  80  *
  81  * Deprecated in favor of `proxmox_backup_new_ns` which includes a namespace parameter.
  82  */
  83 struct ProxmoxBackupHandle *proxmox_backup_new(const char *repo,
  84                                                const char *backup_id,
  85                                                uint64_t backup_time,
  86                                                uint64_t chunk_size,
  87                                                const char *password,
  88                                                const char *keyfile,
  89                                                const char *key_password,
  90                                                const char *master_keyfile,
  91                                                bool compress,
  92                                                bool encrypt,
  93                                                const char *fingerprint,
  94                                                char **error);
  95
  96 /**
  97  * Create a new instance.
  98  *
  99  * `backup_ns` may be NULL and defaults to the root namespace.
 100  *
 101  * Uses `PROXMOX_BACKUP_DEFAULT_CHUNK_SIZE` if `chunk_size` is zero.
 102  */
 103 struct ProxmoxBackupHandle *proxmox_backup_new_ns(const char *repo,
 104                                                   const char *backup_ns,
 105                                                   const char *backup_id,
 106                                                   uint64_t backup_time,
 107                                                   uint64_t chunk_size,
 108                                                   const char *password,
 109                                                   const char *keyfile,
 110                                                   const char *key_password,
 111                                                   const char *master_keyfile,
 112                                                   bool compress,
 113                                                   bool encrypt,
 114                                                   const char *fingerprint,
 115                                                   char **error);
 116
 117 /**
 118  * Open connection to the backup server (sync)
 119  *
 120  * Returns:
 121  *  0 ... Sucecss (no prevbious backup)
 122  *  1 ... Success (found previous backup)
 123  * -1 ... Error
 124  */
 125 int proxmox_backup_connect(struct ProxmoxBackupHandle *handle, char **error);
 126
 127 /**
 128  * Open connection to the backup server
 129  *
 130  * Returns:
 131  *  0 ... Sucecss (no prevbious backup)
 132  *  1 ... Success (found previous backup)
 133  * -1 ... Error
 134  */
 135 void proxmox_backup_connect_async(struct ProxmoxBackupHandle *handle,
 136                                   void (*callback)(void*),
 137                                   void *callback_data,
 138                                   int *result,
 139                                   char **error);
 140
 141 /**
 142  * Abort a running backup task
 143  *
 144  * This stops the current backup task. It is still necessary to call
 145  * proxmox_backup_disconnect() to close the connection and free
 146  * allocated memory.
 147  */
 148 void proxmox_backup_abort(struct ProxmoxBackupHandle *handle, const char *reason);
 149
 150 /**
 151  * Check if we can do incremental backups.
 152  *
 153  * This method compares the csum from last backup manifest with the
 154  * checksum stored locally.
 155  */
 156 int proxmox_backup_check_incremental(struct ProxmoxBackupHandle *handle,
 157                                      const char *device_name,
 158                                      uint64_t size);
 159
 160 /**
 161  * Register a backup image (sync)
 162  */
 163 int proxmox_backup_register_image(struct ProxmoxBackupHandle *handle,
 164                                   const char *device_name,
 165                                   uint64_t size,
 166                                   bool incremental,
 167                                   char **error);
 168
 169 /**
 170  * Register a backup image
 171  *
 172  * Create a new image archive on the backup server
 173  * ('<device_name>.img.fidx'). The returned integer is the dev_id
 174  * parameter for the proxmox_backup_write_data_async() method.
 175  */
 176 void proxmox_backup_register_image_async(struct ProxmoxBackupHandle *handle,
 177                                          const char *device_name,
 178                                          uint64_t size,
 179                                          bool incremental,
 180                                          void (*callback)(void*),
 181                                          void *callback_data,
 182                                          int *result,
 183                                          char **error);
 184
 185 /**
 186  * Add a configuration blob to the backup (sync)
 187  */
 188 int proxmox_backup_add_config(struct ProxmoxBackupHandle *handle,
 189                               const char *name,
 190                               const uint8_t *data,
 191                               uint64_t size,
 192                               char **error);
 193
 194 /**
 195  * Add a configuration blob to the backup
 196  *
 197  * Create and upload a data blob "<name>.blob".
 198  */
 199 void proxmox_backup_add_config_async(struct ProxmoxBackupHandle *handle,
 200                                      const char *name,
 201                                      const uint8_t *data,
 202                                      uint64_t size,
 203                                      void (*callback)(void*),
 204                                      void *callback_data,
 205                                      int *result,
 206                                      char **error);
 207
 208 /**
 209  * Write data to into a registered image (sync)
 210  *
 211  * Upload a chunk of data for the <dev_id> image.
 212  *
 213  * The data pointer may be NULL in order to write the zero chunk
 214  * (only allowed if size == chunk_size)
 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 int proxmox_backup_write_data(struct ProxmoxBackupHandle *handle,
 222                               uint8_t dev_id,
 223                               const uint8_t *data,
 224                               uint64_t offset,
 225                               uint64_t size,
 226                               char **error);
 227
 228 /**
 229  * Write data to into a registered image
 230  *
 231  * Upload a chunk of data for the <dev_id> image.
 232  *
 233  * The data pointer may be NULL in order to write the zero chunk
 234  * (only allowed if size == chunk_size)
 235  *
 236  * Note: The data pointer needs to be valid until the async
 237  * opteration is finished.
 238  *
 239  * Returns:
 240  * -1: on error
 241  *  0: successful, chunk already exists on server, so it was resued
 242  *  size: successful, chunk uploaded
 243  */
 244 void proxmox_backup_write_data_async(struct ProxmoxBackupHandle *handle,
 245                                      uint8_t dev_id,
 246                                      const uint8_t *data,
 247                                      uint64_t offset,
 248                                      uint64_t size,
 249                                      void (*callback)(void*),
 250                                      void *callback_data,
 251                                      int *result,
 252                                      char **error);
 253
 254 /**
 255  * Close a registered image (sync)
 256  */
 257 int proxmox_backup_close_image(struct ProxmoxBackupHandle *handle, uint8_t dev_id, char **error);
 258
 259 /**
 260  * Close a registered image
 261  *
 262  * Mark the image as closed. Further writes are not possible.
 263  */
 264 void proxmox_backup_close_image_async(struct ProxmoxBackupHandle *handle,
 265                                       uint8_t dev_id,
 266                                       void (*callback)(void*),
 267                                       void *callback_data,
 268                                       int *result,
 269                                       char **error);
 270
 271 /**
 272  * Finish the backup (sync)
 273  */
 274 int proxmox_backup_finish(struct ProxmoxBackupHandle *handle, char **error);
 275
 276 /**
 277  * Finish the backup
 278  *
 279  * Finish the backup by creating and uploading the backup manifest.
 280  * All registered images have to be closed before calling this.
 281  */
 282 void proxmox_backup_finish_async(struct ProxmoxBackupHandle *handle,
 283                                  void (*callback)(void*),
 284                                  void *callback_data,
 285                                  int *result,
 286                                  char **error);
 287
 288 /**
 289  * Disconnect and free allocated memory
 290  *
 291  * The handle becomes invalid after this call.
 292  */
 293 void proxmox_backup_disconnect(struct ProxmoxBackupHandle *handle);
 294
 295 /**
 296  * DEPRECATED: Connect the the backup server for restore (sync)
 297  *
 298  * Deprecated in favor of `proxmox_restore_new_ns` which includes a namespace parameter.
 299  * Also, it used "lossy" utf8 decoding on the snapshot name which is not the case in the new
 300  * version anymore.
 301  */
 302 struct ProxmoxRestoreHandle *proxmox_restore_new(const char *repo,
 303                                                  const char *snapshot,
 304                                                  const char *password,
 305                                                  const char *keyfile,
 306                                                  const char *key_password,
 307                                                  const char *fingerprint,
 308                                                  char **error);
 309
 310 /**
 311  * Connect the the backup server for restore (sync)
 312  */
 313 struct ProxmoxRestoreHandle *proxmox_restore_new_ns(const char *repo,
 314                                                     const char *snapshot,
 315                                                     const char *namespace_,
 316                                                     const char *password,
 317                                                     const char *keyfile,
 318                                                     const char *key_password,
 319                                                     const char *fingerprint,
 320                                                     char **error);
 321
 322 /**
 323  * Open connection to the backup server (sync)
 324  *
 325  * Returns:
 326  *  0 ... Sucecss (no prevbious backup)
 327  * -1 ... Error
 328  */
 329 int proxmox_restore_connect(struct ProxmoxRestoreHandle *handle, char **error);
 330
 331 /**
 332  * Open connection to the backup server (async)
 333  *
 334  * Returns:
 335  *  0 ... Sucecss (no prevbious backup)
 336  * -1 ... Error
 337  */
 338 void proxmox_restore_connect_async(struct ProxmoxRestoreHandle *handle,
 339                                    void (*callback)(void*),
 340                                    void *callback_data,
 341                                    int *result,
 342                                    char **error);
 343
 344 /**
 345  * Disconnect and free allocated memory
 346  *
 347  * The handle becomes invalid after this call.
 348  */
 349 void proxmox_restore_disconnect(struct ProxmoxRestoreHandle *handle);
 350
 351 /**
 352  * Restore an image (sync)
 353  *
 354  * Image data is downloaded and sequentially dumped to the callback.
 355  */
 356 int proxmox_restore_image(struct ProxmoxRestoreHandle *handle,
 357                           const char *archive_name,
 358                           int (*callback)(void*, uint64_t, const unsigned char*, uint64_t),
 359                           void *callback_data,
 360                           char **error,
 361                           bool verbose);
 362
 363 /**
 364  * Retrieve the ID of a handle used to access data in the given archive (sync)
 365  */
 366 int proxmox_restore_open_image(struct ProxmoxRestoreHandle *handle,
 367                                const char *archive_name,
 368                                char **error);
 369
 370 /**
 371  * Retrieve the ID of a handle used to access data in the given archive (async)
 372  */
 373 void proxmox_restore_open_image_async(struct ProxmoxRestoreHandle *handle,
 374                                       const char *archive_name,
 375                                       void (*callback)(void*),
 376                                       void *callback_data,
 377                                       int *result,
 378                                       char **error);
 379
 380 /**
 381  * Retrieve the length of a given archive handle in bytes
 382  */
 383 long proxmox_restore_get_image_length(struct ProxmoxRestoreHandle *handle,
 384                                       uint8_t aid,
 385                                       char **error);
 386
 387 /**
 388  * Read data from the backup image at the given offset (sync)
 389  *
 390  * Reads up to size bytes from handle aid at offset. On success,
 391  * returns the number of bytes read. (a return of zero indicates end
 392  * of file).
 393  *
 394  * Note: It is not an error for a successful call to transfer fewer
 395  * bytes than requested.
 396  */
 397 int proxmox_restore_read_image_at(struct ProxmoxRestoreHandle *handle,
 398                                   uint8_t aid,
 399                                   uint8_t *data,
 400                                   uint64_t offset,
 401                                   uint64_t size,
 402                                   char **error);
 403
 404 /**
 405  * Read data from the backup image at the given offset (async)
 406  *
 407  * Reads up to size bytes from handle aid at offset. On success,
 408  * returns the number of bytes read. (a return of zero indicates end
 409  * of file).
 410  *
 411  * Note: The data pointer needs to be valid until the async
 412  * opteration is finished.
 413  *
 414  * Note: The call will only ever transfer less than 'size' bytes if
 415  * the end of the file has been reached.
 416  */
 417 void proxmox_restore_read_image_at_async(struct ProxmoxRestoreHandle *handle,
 418                                          uint8_t aid,
 419                                          uint8_t *data,
 420                                          uint64_t offset,
 421                                          uint64_t size,
 422                                          void (*callback)(void*),
 423                                          void *callback_data,
 424                                          int *result,
 425                                          char **error);
 426
 427 /**
 428  * Serialize all state data into a byte buffer. Can be loaded again with
 429  * proxmox_import_state. Use for migration for example.
 430  *
 431  * Length of the returned buffer is written to buf_size. Returned buffer must
 432  * be freed with proxmox_free_state_buf.
 433  */
 434 uint8_t *proxmox_export_state(uintptr_t *buf_size);
 435
 436 /**
 437  * Load state serialized by proxmox_export_state. If loading fails, a message
 438  * will be logged to stderr, but the function will not fail.
 439  */
 440 void proxmox_import_state(const uint8_t *buf, uintptr_t buf_size);
 441
 442 /**
 443  * Free a buffer acquired from proxmox_export_state.
 444  */
 445 void proxmox_free_state_buf(uint8_t *buf);
 446
 447 #endif /* PROXMOX_BACKUP_QEMU_H */