HV_VSS(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 hv_vss — Hyper-V Volume Shadow Copy Service API 💖

okay bestie, welcome to hv_vss(4), the kernel interfaces manual page that's basically the group chat between your FreeBSD VM and a Hyper-V host. it's giving "middle school go-between passing notes" energy, but make it storage. let's get into it 🦋

✨ SYNOPSIS ✨

so first off, you gotta pull in the header:

#include <dev/hyperv/hv_snapshot.h>

then we've got the two status defines, the operation enum, and the message struct. slay:

#define VSS_SUCCESS             0x00000000
#define VSS_FAIL                0x00000001

enum hv_vss_op_t {
        HV_VSS_NONE = 0,
        HV_VSS_CHECK,
        HV_VSS_FREEZE,
        HV_VSS_THAW,
        HV_VSS_COUNT
};

struct hv_vss_opt_msg {
        uint32_t        opt;            /* operation */
        uint32_t        status;         /* 0 for success, 1 for error */
        uint64_t        msgid;          /* an ID used to identify the transaction */
        uint8_t         reserved[48];   /* reserved values are all zeroes */
};

no cap, those reserved[48] bytes are just vibing there, all zeroes, minding their own business 💅

🌸 DESCRIPTION 🌸

okay so here's the whole why of this thing. the freeze or thaw functionality of an application is important — like, genuinely important — to guarantee the application consistent backup. 🔥

on the windows platform, VSS is defined to do live backup. but for a VM guest running on Hyper-V, the corresponding VSS is not defined yet. take a running database server instance: it knows when the applications' freeze/thaw should start or finish. iconic. but it is not aware of the freeze/thaw notification coming from the Hyper-V host. rude, honestly. 🙈

so hv_vss is designed to notify the application of the freeze/thaw request. that's the whole gig. it plays the role of broker — forwarding the freeze/thaw command from the Hyper-V host to the userland application if that app registered VSS service on the FreeBSD VM, and then sending the result back to the Hyper-V host. main character energy, truly. 👑

🧚 the general flow, bestie

generally, hv_vss_daemon(8) takes the responsibility to freeze/thaw the UFS file system, and it is automatically launched after system boots. so it's already there, holding it down. ✨

when the Hyper-V host wants to take a snapshot of the FreeBSD VM, it will first send a VSS capability check to the FreeBSD VM. hv_vss received the request and forward the request to the userland application if it is registered.

only after hv_vss received the VSS_SUCCESS response from the application, the hv_vss_daemon(8) will be informed to check whether file system freeze/thaw is supported. 💖

if any error occurs during this period, hv_vss will inform the Hyper-V host that VSS is not supported. sad but honest.

in addition, there is a default timeout limit before sending a response to the Hyper-V host. if the total response time from the application and hv_vss_daemon(8) exceeds this value, timeout will occur and VSS unsupported is responded to the Hyper-V host. 😭

🥶 freeze me like one of your snapshots

after the Hyper-V host confirmed the FreeBSD VM supports VSS, it will send a freeze request to the VM, and hv_vss will first forward it to the application. after the application finished freezing, it should inform hv_vss and then the file system level freezing will be triggered by hv_vss_daemon(8).

after all freezing on both the application and hv_vss_daemon(8) were finished, hv_vss will inform the Hyper-V host that freezing is done. ✅

of course, there is a timeout limit as same as VSS capability is set, to make sure freezing on the FreeBSD VM is not hang. if there is any error occurs or timeout happened, the freezing is failed on the Hyper-V side. 💀

🔥 thaw it out, periodt

the Hyper-V host will send a thaw request after taking the snapshot. typically, this period is very short in order not to block the running application. 🫶

hv_vss firstly thaws the file system by notifying hv_vss_daemon(8), then notifies the user registered application. there is also a timeout check before sending a response to the Hyper-V host.

⏰ the timeout tea

all the default timeout limit used in VSS capability check, freeze or thaw is the same. it is 15 seconds currently. that's the number. remember it. 🎀

👑 NOTES 👑

  • hv_vss only supports UFS currently. if any of the file system partition is non UFS, the VSS capability check will fail. 🚫
  • if the application does not register VSS, hv_vss only supports backup for file system level consistent. iykyk.
  • the device should be closed before it was opened again. if you want to simultaneously open "/dev/hv_appvss_dev" two or more times, an error (-1) will be returned, and errno was set. 🙈
if hv_vss_daemon(8) was killed after system boots, the VSS functionality will not work. fr fr. 💔

more parts incoming, bestie — don't go anywhere 💜

🌈 EXAMPLES 🌈

okay bestie, here's the whole vibe in one file 💖 this is a complete example that does absolutely nothing useful except sit there and wait 2 seconds whenever it catches one of those notifications from hv_vss. that's it. that's the whole job. iconic behavior, honestly 🫶

#include <string.h>
#include <stdio.h>
#include <sys/ioctl.h>
#include <sys/param.h>
#include <sys/ucred.h>
#include <sys/mount.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>
#include <poll.h>
#include <stdint.h>
#include <syslog.h>
#include <errno.h>
#include <err.h>
#include <fcntl.h>
#include <ufs/ffs/fs.h>
#include <paths.h>
#include <sys/ioccom.h>
#include <dev/hyperv/hv_snapshot.h>

#define UNDEF_FREEZE_THAW       (0)
#define FREEZE                  (1)
#define THAW                    (2)
#define CHECK                   (3)

#define VSS_LOG(priority, format, args...) do   {                               \
        if (is_debugging == 1) {                                        \
            if (is_daemon == 1)                                     \
                syslog(priority, format, ## args);              \
            else                                                    \
                printf(format, ## args);                        \
        } else {                                                        \
            if (priority < LOG_DEBUG) {                             \
                if (is_daemon == 1)                             \
                    syslog(priority, format, ## args);      \
                else                                            \
                    printf(format, ## args);                \
            }                                                       \
        }                                                               \
    } while(0)

#define CHECK_TIMEOUT           1
#define CHECK_FAIL              2
#define FREEZE_TIMEOUT          1
#define FREEZE_FAIL             2
#define THAW_TIMEOUT            1
#define THAW_FAIL               2

static int is_daemon        = 1;
static int is_debugging     = 0;
static int simu_opt_waiting = 2; // seconds

#define GENERIC_OPT(TIMEOUT, FAIL)                                              \
    do {                                                                    \
        sleep(simu_opt_waiting);                                        \
        if (opt == CHECK_TIMEOUT) {                                     \
            sleep(simu_opt_waiting * 10);                           \
            VSS_LOG(LOG_INFO, "%s timeout simulation\n",            \
                __func__);                                          \
            return (0);                                             \
        } else if (opt == CHECK_FAIL) {                                 \
            VSS_LOG(LOG_INFO, "%s failure simulation\n",            \
                __func__);                                          \
            return (CHECK_FAIL);                                    \
        } else {                                                        \
            VSS_LOG(LOG_INFO, "%s success simulation\n",            \
                __func__);                                          \
            return (0);                                             \
        }                                                               \
    } while (0)

static int
check(int opt)
{
    GENERIC_OPT(CHECK_TIMEOUT, CHECK_FAIL);
}

static int
freeze(int opt)
{
    GENERIC_OPT(FREEZE_TIMEOUT, FREEZE_FAIL);
}

static int
thaw(int opt)
{
    GENERIC_OPT(THAW_TIMEOUT, THAW_FAIL);
}

static void usage(const char* cmd) {
    fprintf(stderr,
        "%s -f <0|1|2>: simulate app freeze."
        " 0: successful, 1: freeze timeout, 2: freeze failed\n"
        " -c <0|1|2>: simulate vss feature check"
        " -t <0|1|2>: simulate app thaw."
        " 0: successful, 1: freeze timeout, 2: freeze failed\n"
        " -d : enable debug mode\n"
        " -n : run this tool under non-daemon mode\n", cmd);
}

int
main(int argc, char* argv[]) {
    int ch, freezesimuop = 0, thawsimuop = 0, checksimuop = 0, fd, r, error;
    uint32_t op;
    struct pollfd app_vss_fd[1];
    struct hv_vss_opt_msg  userdata;

    while ((ch = getopt(argc, argv, "f:c:t:dnh")) != -1) {
        switch (ch) {
        case 'f':
            /* Run as regular process for debugging purpose. */
            freezesimuop = (int)strtol(optarg, NULL, 10);
            break;
        case 't':
            thawsimuop = (int)strtol(optarg, NULL, 10);
            break;
        case 'c':
            checksimuop = (int)strtol(optarg, NULL, 10);
            break;
        case 'd':
            is_debugging = 1;
            break;
        case 'n':
            is_daemon = 0;
            break;
        case 'h':
        default:
            usage(argv[0]);
            exit(0);
        }
    }

    openlog("APPVSS", 0, LOG_USER);
    /* Become daemon first. */
    if (is_daemon == 1)
        daemon(1, 0);
    else
        VSS_LOG(LOG_DEBUG, "Run as regular process.\n");

    VSS_LOG(LOG_INFO, "HV_VSS starting; pid is: %d\n", getpid());

    fd = open(VSS_DEV(APP_VSS_DEV_NAME), O_RDWR);
    if (fd < 0) {
        VSS_LOG(LOG_ERR, "Fail to open %s, error: %d %s\n",
            VSS_DEV(APP_VSS_DEV_NAME), errno, strerror(errno));
        exit(EXIT_FAILURE);
    }
    app_vss_fd[0].fd     = fd;
    app_vss_fd[0].events = POLLIN | POLLRDNORM;

    while (1) {
        r = poll(app_vss_fd, 1, INFTIM);

        VSS_LOG(LOG_DEBUG, "poll returned r = %d, revent = 0x%x\n",
            r, app_vss_fd[0].revents);

        if (r == 0 || (r < 0 && errno == EAGAIN) ||
            (r < 0 && errno == EINTR)) {
            /* Nothing to read */
            continue;
        }

        if (r < 0) {
            /*
             * For poll return failure other than EAGAIN,
             * we want to exit.
             */
            VSS_LOG(LOG_ERR, "Poll failed.\n");
            perror("poll");
            exit(EIO);
        }

        /* Read from character device */
        error = ioctl(fd, IOCHVVSSREAD, &userdata);
        if (error < 0) {
            VSS_LOG(LOG_ERR, "Read failed.\n");
            perror("pread");
            exit(EIO);
        }

        if (userdata.status != 0) {
            VSS_LOG(LOG_ERR, "data read error\n");
            continue;
        }

        op = userdata.opt;

        switch (op) {
        case HV_VSS_CHECK:
            error = check(checksimuop);
            break;
        case HV_VSS_FREEZE:
            error = freeze(freezesimuop);
            break;
        case HV_VSS_THAW:
            error = thaw(thawsimuop);
            break;
        default:
            VSS_LOG(LOG_ERR, "Illegal operation: %d\n", op);
            error = VSS_FAIL;
        }
        if (error)
            userdata.status = VSS_FAIL;
        else
            userdata.status = VSS_SUCCESS;
        error = ioctl(fd, IOCHVVSSWRITE, &userdata);
        if (error != 0) {
            VSS_LOG(LOG_ERR, "Fail to write to device\n");
            exit(EXIT_FAILURE);
        } else {
            VSS_LOG(LOG_INFO, "Send response %d for %s to kernel\n",
                userdata.status, op == HV_VSS_FREEZE ? "Freeze" :
                (op == HV_VSS_THAW ? "Thaw" : "Check"));
        }
    }
    return 0;
}

👀 SEE ALSO 👀

go read your sisters bestie, they're all connected 💅

📜 HISTORY 📜

the daemon dropped in October 2016 and was developed by Microsoft Corp. yes, a whole origin story 🎀

💖 AUTHORS 💖

FreeBSD support for hv_vss was first added by Microsoft BSD Integration Services Team <bsdic@microsoft.com>. absolute legends, no cap 🫶

and that's the whole page bestie, you made it to the end 🎉 this lil cutie comes to you from Debian, dated October 12, 2016 — go forth and snapshot responsibly 💜✨

📦 where this page comes from