This program allows you to turn a network block device source into a FUSE filesystem containing a virtual file: $ nbdkit memory 128M $ mkdir mp $ nbdfuse mp/ramdisk nbd://localhost & $ ls -l mp total 0 -rw-rw-rw-. 1 rjones rjones 134217728 Oct 12 15:09 ramdisk $ dd if=/dev/urandom bs=1M count=128 of=mp/ramdisk conv=notrunc,nocreat 128+0 records in 128+0 records out 134217728 bytes (134 MB, 128 MiB) copied, 3.10171 s, 43.3 MB/s $ fusermount -u mp There are still some shortcomings, such as lack of zero and trim support. These are documented in the TODO file. Now for some history: In libguestfs which is where most of this code derives from we have a program called ‘guestmount’ which is a FUSE interface to libguestfs: http://libguestfs.org/guestmount.1.html Originally that was a standalone program like nbdfuse, but after some time we realized that the ability to mount libguestfs under a directory was generally useful to all guestfs API users and we created new APIs for it. guestmount has now become a thin wrapper around those APIs. This of course argues that we should do the same thing for libnbd. But ... (1) For NBD this is a little less useful than for libguestfs. (2) We can always do this in future if we need to. Most importantly: (3) the libguestfs FUSE API turned out to have a problem - still unresolved - with handling threads and SELinux and it may not be a good idea to bake this into the libnbd API until that problem has been solved. For more details about (3), read this: https://bugzilla.redhat.com/show_bug.cgi?id=1060423#c2 --- .gitignore | 2 + Makefile.am | 3 +- README | 2 + TODO | 7 + configure.ac | 18 ++ docs/libnbd.pod | 1 + fuse/Makefile.am | 60 +++++ fuse/nbdfuse.c | 590 ++++++++++++++++++++++++++++++++++++++++++++ fuse/nbdfuse.pod | 262 ++++++++++++++++++++ fuse/test-nbdkit.sh | 63 +++++ fuse/test-qcow2.sh | 64 +++++ run.in | 1 + sh/nbdsh.pod | 1 + 13 files changed, 1073 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 1970e6c..f2654a3 100644 --- a/.gitignore +++ b/.gitignore @@ -57,6 +57,8 @@ Makefile.in /examples/server-flags /examples/strict-structured-reads /examples/threaded-reads-and-writes +/fuse/nbdfuse +/fuse/nbdfuse.1 /fuzzing/libnbd-fuzz-wrapper /fuzzing/sync_dir/ /generator/generator-cache.v1 diff --git a/Makefile.am b/Makefile.am index b2d9dca..568e735 100644 --- a/Makefile.am +++ b/Makefile.am @@ -39,6 +39,7 @@ SUBDIRS = \ tests \ python \ sh \ + fuse \ ocaml \ ocaml/examples \ ocaml/tests \ @@ -64,7 +65,7 @@ maintainer-check-extra-dist: @echo PASS: EXTRA_DIST tests check-valgrind: all - @for d in tests ocaml/tests interop; do \ + @for d in tests fuse ocaml/tests interop; do \ $(MAKE) -C $$d check-valgrind || exit 1; \ done diff --git a/README b/README index 1c9d816..8d6b563 100644 --- a/README +++ b/README @@ -82,6 +82,8 @@ Optional: * Python >= 3.3 to build the Python 3 bindings and NBD shell (nbdsh). + * FUSE to build the nbdfuse program. + Optional, only needed to run the test suite: * nbdkit >= 1.12, the nbdkit basic plugins and the nbdkit basic diff --git a/TODO b/TODO index 71d678b..8b7dbe4 100644 --- a/TODO +++ b/TODO @@ -27,6 +27,13 @@ Should we ship a "nbdcp" copying tool? - Could upload, download or copy between servers. - Duplicates functionality already available in qemu-img convert. +nbdfuse: + - If you write beyond the end of the virtual file, it returns EIO. + - Implement trim/discard. + - Implement write_zeroes. + - Implement block_status. + - Could be made multithreaded for improved performance. + Suggested API improvements: general: - synchronous APIs that have a timeout or can be cancelled diff --git a/configure.ac b/configure.ac index fde43dc..96cb4bd 100644 --- a/configure.ac +++ b/configure.ac @@ -200,6 +200,23 @@ PKG_CHECK_MODULES([GLIB], [glib-2.0], [ ]) AM_CONDITIONAL([HAVE_GLIB], [test "x$GLIB_LIBS" != "x"]) +dnl FUSE is optional to build the FUSE module. +AC_ARG_ENABLE([fuse], + AS_HELP_STRING([--disable-fuse], [disable FUSE (guestmount) support]), + [], + [enable_fuse=yes]) +AS_IF([test "x$enable_fuse" != "xno"],[ + PKG_CHECK_MODULES([FUSE],[fuse],[ + AC_SUBST([FUSE_CFLAGS]) + AC_SUBST([FUSE_LIBS]) + AC_DEFINE([HAVE_FUSE],[1],[Define to 1 if you have FUSE.]) + ],[ + enable_fuse=no + AC_MSG_WARN([FUSE library and headers are missing, so optional FUSE module won't be built]) + ]) +]) +AM_CONDITIONAL([HAVE_FUSE],[test "x$enable_fuse" != "xno"]) + dnl Check we have enough to run podwrapper. AC_CHECK_PROG([PERL],[perl],[perl],[no]) AS_IF([test "x$PERL" != "xno"],[ @@ -353,6 +370,7 @@ AC_CONFIG_FILES([Makefile common/include/Makefile docs/Makefile examples/Makefile + fuse/Makefile fuzzing/Makefile generator/Makefile include/Makefile diff --git a/docs/libnbd.pod b/docs/libnbd.pod index 2c3eaf4..9ab6150 100644 --- a/docs/libnbd.pod +++ b/docs/libnbd.pod @@ -840,6 +840,7 @@ L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md>;. L<libnbd-security(3)>, L<nbdsh(1)>, +L<nbdfuse(1)>, L<qemu(1)>. =head1 AUTHORS diff --git a/fuse/Makefile.am b/fuse/Makefile.am new file mode 100644 index 0000000..3d827aa --- /dev/null +++ b/fuse/Makefile.am @@ -0,0 +1,60 @@ +# nbd client library in userspace +# Copyright (C) 2013-2019 Red Hat Inc. +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +include $(top_srcdir)/subdir-rules.mk + +EXTRA_DIST = \ + nbdfuse.pod \ + test-nbdkit.sh \ + test-qcow2.sh \ + $(NULL) + +TESTS_ENVIRONMENT = LIBNBD_DEBUG=1 +LOG_COMPILER = $(top_builddir)/run +TESTS = + +if HAVE_FUSE + +bin_PROGRAMS = nbdfuse + +nbdfuse_SOURCES = nbdfuse.c +nbdfuse_CPPFLAGS = -I$(top_srcdir)/include +nbdfuse_CFLAGS = $(WARNINGS_CFLAGS) $(FUSE_CFLAGS) +nbdfuse_LDADD = $(top_builddir)/lib/libnbd.la $(FUSE_LIBS) + +if HAVE_POD + +man_MANS = \ + nbdfuse.1 \ + $(NULL) + +nbdfuse.1: nbdfuse.pod $(top_builddir)/podwrapper.pl + $(PODWRAPPER) --section=1 --man $@ \ + --html $(top_builddir)/html/$@.html \ + $< + +endif HAVE_POD + +TESTS += \ + test-nbdkit.sh \ + test-qcow2.sh \ + $(NULL) + +check-valgrind: + LIBNBD_VALGRIND=1 $(MAKE) check + +endif HAVE_FUSE diff --git a/fuse/nbdfuse.c b/fuse/nbdfuse.c new file mode 100644 index 0000000..5703b95 --- /dev/null +++ b/fuse/nbdfuse.c @@ -0,0 +1,590 @@ +/* NBD client library in userspace + * Copyright (C) 2013-2019 Red Hat Inc. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/* FUSE support. */ + +#include <config.h> + +#include <stdio.h> +#include <stdlib.h> +#include <stdbool.h> +#include <stdint.h> +#include <string.h> +#include <getopt.h> +#include <limits.h> +#include <fcntl.h> +#include <unistd.h> +#include <errno.h> +#include <signal.h> +#include <time.h> +#include <sys/types.h> +#include <sys/stat.h> + +#define FUSE_USE_VERSION 26 + +#include <fuse.h> +#include <fuse_lowlevel.h> + +#include <libnbd.h> + +#define MAX_REQUEST_SIZE (64 * 1024 * 1024) + +static struct nbd_handle *nbd; +static bool readonly = false; +static char *mountpoint, *filename; +static const char *pidfile; +static char *fuse_options; +static struct fuse_chan *ch; +static struct fuse *fuse; +static struct timespec start_t; +static uint64_t size; + +static int nbdfuse_getattr (const char *path, struct stat *stbuf); +static int nbdfuse_readdir (const char *path, void *buf, + fuse_fill_dir_t filler, + off_t offset, struct fuse_file_info *fi); +static int nbdfuse_open (const char *path, struct fuse_file_info *fi); +static int nbdfuse_read (const char *path, char *buf, + size_t count, off_t offset, + struct fuse_file_info *fi); +static int nbdfuse_write (const char *path, const char *buf, + size_t count, off_t offset, + struct fuse_file_info *fi); +static int nbdfuse_fsync (const char *path, int datasync, + struct fuse_file_info *fi); +static int nbdfuse_release (const char *path, struct fuse_file_info *fi); + +static struct fuse_operations fuse_operations = { + .getattr = nbdfuse_getattr, + .readdir = nbdfuse_readdir, + .open = nbdfuse_open, + .read = nbdfuse_read, + .write = nbdfuse_write, + .fsync = nbdfuse_fsync, + .release = nbdfuse_release, +}; + +static void __attribute__((noreturn)) +usage (FILE *fp, int exitcode) +{ + fprintf (fp, +" nbdfuse [-r] MOUNTPOINT[/FILENAME] URI\n" +"Other modes:\n" +" nbdfuse MOUNTPOINT[/FILENAME] --command CMD [ARGS ...]\n" +" nbdfuse MOUNTPOINT[/FILENAME] --socket-activation CMD [ARGS ...]\n" +" nbdfuse MOUNTPOINT[/FILENAME] --fd N\n" +" nbdfuse MOUNTPOINT[/FILENAME] --tcp HOST PORT\n" +" nbdfuse MOUNTPOINT[/FILENAME] --unix SOCKET\n" +"\n" +"Please read the nbdfuse(1) manual page for full usage.\n" +); + exit (exitcode); +} + +static void +display_version (void) +{ + printf ("%s %s\n", PACKAGE_NAME, PACKAGE_VERSION); +} + +static void +fuse_help (const char *prog) +{ + static struct fuse_operations null_operations; + const char *tmp_argv[] = { prog, "--help", NULL }; + fuse_main (2, (char **) tmp_argv, &null_operations, NULL); + exit (EXIT_SUCCESS); +} + +static bool +is_directory (const char *path) +{ + struct stat statbuf; + + if (stat (path, &statbuf) == -1) + return false; + return S_ISDIR (statbuf.st_mode); +} + +int +main (int argc, char *argv[]) +{ + enum { + MODE_URI, + MODE_COMMAND, + MODE_FD, + MODE_SOCKET_ACTIVATION, + MODE_TCP, + MODE_UNIX, + } mode = MODE_URI; + enum { + HELP_OPTION = CHAR_MAX + 1, + FUSE_HELP_OPTION, + }; + /* Note the "+" means we stop processing as soon as we get to the + * first non-option argument (the mountpoint) and then we parse the + * rest of the command line without getopt. + */ + const char *short_options = "+o:P:rV"; + const struct option long_options[] = { + { "fuse-help", no_argument, NULL, FUSE_HELP_OPTION }, + { "help", no_argument, NULL, HELP_OPTION }, + { "pidfile", required_argument, NULL, 'P' }, + { "pid-file", required_argument, NULL, 'P' }, + { "readonly", no_argument, NULL, 'r' }, + { "read-only", no_argument, NULL, 'r' }, + { "version", no_argument, NULL, 'V' }, + + { NULL } + }; + int c, fd, r; + int64_t ssize; + const char *s; + struct fuse_args fuse_args = FUSE_ARGS_INIT (0, NULL); + struct sigaction sa; + FILE *fp; + + for (;;) { + c = getopt_long (argc, argv, short_options, long_options, NULL); + if (c == -1) + break; + + switch (c) { + case HELP_OPTION: + usage (stdout, EXIT_SUCCESS); + + case FUSE_HELP_OPTION: + fuse_help (argv[0]); + exit (EXIT_SUCCESS); + + case 'o': + fuse_opt_add_opt_escaped (&fuse_options, optarg); + break; + + case 'P': + pidfile = optarg; + break; + + case 'r': + readonly = true; + break; + + case 'V': + display_version (); + exit (EXIT_SUCCESS); + + default: + fprintf (stderr, "\n"); + usage (stderr, EXIT_FAILURE); + } + } + + /* There must be at least 2 parameters (mountpoint and + * URI/--command/etc). + */ + if (argc - optind < 2) + usage (stderr, EXIT_FAILURE); + + /* Parse and check the mountpoint. It might be MOUNTPOINT or + * MOUNTPOINT/FILENAME. In either case MOUNTPOINT must be an + * existing directory. + */ + s = argv[optind++]; + if (is_directory (s)) { + mountpoint = strdup (s); + filename = strdup ("nbd"); + if (mountpoint == NULL || filename == NULL) { + strdup_error: + perror ("strdup"); + exit (EXIT_FAILURE); + } + } + else { + const char *p = strrchr (s, '/'); + + if (p == NULL) { + mp_error: + fprintf (stderr, "%s: %s: " + "mountpoint must be \"directory\" or \"directory/filename\"\n", + argv[0], s); + exit (EXIT_FAILURE); + } + mountpoint = strndup (s, p-s); + if (mountpoint == NULL) goto strdup_error; + if (! is_directory (mountpoint)) goto mp_error; + if (strlen (p+1) == 0) goto mp_error; + filename = strdup (p+1); + if (filename == NULL) goto strdup_error; + } + + /* The next parameter is either a URI or a mode switch. */ + if (strcmp (argv[optind], "--command") == 0 || + strcmp (argv[optind], "--cmd") == 0) { + mode = MODE_COMMAND; + optind++; + } + else if (strcmp (argv[optind], "--socket-activation") == 0 || + strcmp (argv[optind], "--systemd-socket-activation") == 0) { + mode = MODE_SOCKET_ACTIVATION; + optind++; + } + else if (strcmp (argv[optind], "--fd") == 0) { + mode = MODE_FD; + optind++; + } + else if (strcmp (argv[optind], "--tcp") == 0) { + mode = MODE_TCP; + optind++; + } + else if (strcmp (argv[optind], "--unix") == 0) { + mode = MODE_UNIX; + optind++; + } + else if (argv[optind][0] == '-') { + fprintf (stderr, "%s: unknown mode: %s\n\n", argv[0], argv[optind]); + usage (stderr, EXIT_FAILURE); + } + + /* Check there are enough parameters following given the mode. */ + switch (mode) { + case MODE_URI: + case MODE_FD: + case MODE_UNIX: + if (argc - optind != 1) + usage (stderr, EXIT_FAILURE); + break; + case MODE_TCP: + if (argc - optind != 2) + usage (stderr, EXIT_FAILURE); + break; + case MODE_COMMAND: + case MODE_SOCKET_ACTIVATION: + if (argc - optind < 1) + usage (stderr, EXIT_FAILURE); + break; + } + /* At this point we know the command line is valid, and so can start + * opening FUSE and libnbd. + */ + + /* Create the libnbd handle. */ + nbd = nbd_create (); + if (nbd == NULL) { + fprintf (stderr, "%s\n", nbd_get_error ()); + exit (EXIT_FAILURE); + } + + /* Connect to the NBD server synchronously. */ + switch (mode) { + case MODE_URI: + if (nbd_connect_uri (nbd, argv[optind]) == -1) { + fprintf (stderr, "%s\n", nbd_get_error ()); + exit (EXIT_FAILURE); + } + break; + + case MODE_COMMAND: + if (nbd_connect_command (nbd, &argv[optind]) == -1) { + fprintf (stderr, "%s\n", nbd_get_error ()); + exit (EXIT_FAILURE); + } + break; + + case MODE_SOCKET_ACTIVATION: + if (nbd_connect_systemd_socket_activation (nbd, &argv[optind]) == -1) { + fprintf (stderr, "%s\n", nbd_get_error ()); + exit (EXIT_FAILURE); + } + break; + + case MODE_FD: + if (sscanf (argv[optind], "%d", &fd) != 1) { + fprintf (stderr, "%s: could not parse file descriptor: %s\n\n", + argv[0], argv[optind]); + exit (EXIT_FAILURE); + } + if (nbd_connect_socket (nbd, fd) == -1) { + fprintf (stderr, "%s\n", nbd_get_error ()); + exit (EXIT_FAILURE); + } + break; + + case MODE_TCP: + if (nbd_connect_tcp (nbd, argv[optind], argv[optind+1]) == -1) { + fprintf (stderr, "%s\n", nbd_get_error ()); + exit (EXIT_FAILURE); + } + break; + + case MODE_UNIX: + if (nbd_connect_unix (nbd, argv[optind]) == -1) { + fprintf (stderr, "%s\n", nbd_get_error ()); + exit (EXIT_FAILURE); + } + break; + } + + ssize = nbd_get_size (nbd); + if (ssize == -1) { + fprintf (stderr, "%s\n", nbd_get_error ()); + exit (EXIT_FAILURE); + } + size = (uint64_t) ssize; + + /* This is just used to give an unchanging time when they stat in + * the mountpoint. + */ + clock_gettime (CLOCK_REALTIME, &start_t); + + /* Create the FUSE args. */ + if (fuse_opt_add_arg (&fuse_args, argv[0]) == -1) { + fuse_opt_error: + perror ("fuse_opt_add_arg"); + exit (EXIT_FAILURE); + } + + if (fuse_options) { + if (fuse_opt_add_arg (&fuse_args, "-o") == -1 || + fuse_opt_add_arg (&fuse_args, fuse_options) == -1) + goto fuse_opt_error; + } + + /* Create the FUSE mountpoint. */ + ch = fuse_mount (mountpoint, &fuse_args); + if (ch == NULL) { + fprintf (stderr, + "%s: fuse_mount failed: see error messages above", argv[0]); + exit (EXIT_FAILURE); + } + + /* Set F_CLOEXEC on the channel. Some versions of libfuse don't do + * this. + */ + fd = fuse_chan_fd (ch); + if (fd >= 0) { + int flags = fcntl (fd, F_GETFD, 0); + if (flags >= 0) + fcntl (fd, F_SETFD, flags & ~FD_CLOEXEC); + } + + /* Create the FUSE handle. */ + fuse = fuse_new (ch, &fuse_args, + &fuse_operations, sizeof fuse_operations, NULL); + if (!fuse) { + perror ("fuse_new"); + exit (EXIT_FAILURE); + } + fuse_opt_free_args (&fuse_args); + + /* Catch signals since they can leave the mountpoint in a funny + * state. To exit the program callers must use ‘fusermount -u’. We + * also must be careful not to call exit(2) in this program until we + * have unmounted the filesystem below. + */ + memset (&sa, 0, sizeof sa); + sa.sa_handler = SIG_IGN; + sa.sa_flags = SA_RESTART; + sigaction (SIGPIPE, &sa, NULL); + sigaction (SIGINT, &sa, NULL); + sigaction (SIGQUIT, &sa, NULL); + + /* Ready to serve, write pidfile. */ + if (pidfile) { + fp = fopen (pidfile, "w"); + if (fp) { + fprintf (fp, "%ld", (long) getpid ()); + fclose (fp); + } + } + + /* Enter the main loop. */ + r = fuse_loop (fuse); + if (r != 0) + perror ("fuse_loop"); + + /* Close FUSE. */ + fuse_unmount (mountpoint, ch); + fuse_destroy (fuse); + + /* Close NBD handle. */ + nbd_close (nbd); + + free (mountpoint); + free (filename); + free (fuse_options); + + exit (r == 0 ? EXIT_SUCCESS : EXIT_FAILURE); +} + +/* Wraps calls to libnbd functions and automatically checks for a + * returns errors in the format required by FUSE. It also prints out + * the full error message on stderr, so that we don't lose it. + */ +#define CHECK_NBD_ERROR(CALL) \ + do { if ((CALL) == -1) return check_nbd_error (); } while (0) +static int +check_nbd_error (void) +{ + int err; + + fprintf (stderr, "%s\n", nbd_get_error ()); + err = nbd_get_errno (); + if (err != 0) + return -err; + else + return -EIO; +} + +static int +nbdfuse_getattr (const char *path, struct stat *statbuf) +{ + const int mode = readonly ? 0444 : 0666; + + memset (statbuf, 0, sizeof (struct stat)); + + /* We're probably making some Linux-specific assumptions here, but + * this file is not compiled on non-Linux systems. + */ + statbuf->st_atim = start_t; + statbuf->st_mtim = start_t; + statbuf->st_ctim = start_t; + statbuf->st_uid = geteuid (); + statbuf->st_gid = getegid (); + + if (strcmp (path, "/") == 0) { + /* getattr "/" */ + statbuf->st_mode = S_IFDIR | (mode & 0111); + statbuf->st_nlink = 2; + } + else if (path[0] == '/' && strcmp (path+1, filename) == 0) { + /* getattr "/filename" */ + statbuf->st_mode = S_IFREG | mode; + statbuf->st_nlink = 1; + statbuf->st_size = size; + } + else + return -ENOENT; + + return 0; +} + +static int +nbdfuse_readdir (const char *path, void *buf, + fuse_fill_dir_t filler, + off_t offset, struct fuse_file_info *fi) +{ + if (strcmp (path, "/") != 0) + return -ENOENT; + + filler (buf, ".", NULL, 0); + filler (buf, "..", NULL, 0); + filler (buf, filename, NULL, 0); + + return 0; +} + +/* This function checks the O_RDONLY/O_RDWR flags passed to the + * open(2) call, so we have to check the open mode is compatible with + * the readonly flag. + */ +static int +nbdfuse_open (const char *path, struct fuse_file_info *fi) +{ + if (path[0] != '/' || strcmp (path+1, filename) != 0) + return -ENOENT; + + if (readonly && (fi->flags & O_ACCMODE) != O_RDONLY) + return -EACCES; + + return 0; +} + +static int +nbdfuse_read (const char *path, char *buf, + size_t count, off_t offset, + struct fuse_file_info *fi) +{ + if (path[0] != '/' || strcmp (path+1, filename) != 0) + return -ENOENT; + + if (offset >= size) + return 0; + + if (count > MAX_REQUEST_SIZE) + count = MAX_REQUEST_SIZE; + + if (offset + count > size) + count = size - offset; + + CHECK_NBD_ERROR (nbd_pread (nbd, buf, count, offset, 0)); + + return (int) count; +} + +static int +nbdfuse_write (const char *path, const char *buf, + size_t count, off_t offset, + struct fuse_file_info *fi) +{ + /* Probably shouldn't happen because of nbdfuse_open check. */ + if (readonly) + return -EACCES; + + if (path[0] != '/' || strcmp (path+1, filename) != 0) + return -ENOENT; + + if (offset >= size) + return 0; + + if (count > MAX_REQUEST_SIZE) + count = MAX_REQUEST_SIZE; + + if (offset + count > size) + count = size - offset; + + CHECK_NBD_ERROR (nbd_pwrite (nbd, buf, count, offset, 0)); + + return (int) count; +} + +static int +nbdfuse_fsync (const char *path, int datasync, struct fuse_file_info *fi) +{ + if (readonly) + return 0; + + /* If the server doesn't support flush then the operation is + * silently ignored. + */ + if (nbd_can_flush (nbd)) + CHECK_NBD_ERROR (nbd_flush (nbd, 0)); + + return 0; +} + +/* This is called on the last close of a file. We do a flush here to + * be on the safe side, but it's not strictly necessary. + */ +static int +nbdfuse_release (const char *path, struct fuse_file_info *fi) +{ + if (readonly) + return 0; + + return nbdfuse_fsync (path, 0, fi); +} diff --git a/fuse/nbdfuse.pod b/fuse/nbdfuse.pod new file mode 100644 index 0000000..e43e23c --- /dev/null +++ b/fuse/nbdfuse.pod @@ -0,0 +1,262 @@ +=head1 NAME + +nbdfuse - present a network block device in a FUSE filesystem + +=head1 SYNOPSIS + + nbdfuse [-o FUSE-OPTION] [-P PIDFILE] [-r] + MOUNTPOINT[/FILENAME] URI + +Other modes: + + nbdfuse MOUNTPOINT[/FILENAME] --command CMD [ARGS ...] + + nbdfuse MOUNTPOINT[/FILENAME] --socket-activation CMD [ARGS ...] + + nbdfuse MOUNTPOINT[/FILENAME] --fd N + + nbdfuse MOUNTPOINT[/FILENAME] --tcp HOST PORT + + nbdfuse MOUNTPOINT[/FILENAME] --unix SOCKET + +=head1 DESCRIPTION + +nbdfuse presents a Network Block Device as a local file inside a FUSE +filesystem. + +The FUSE filesystem is mounted at F<MOUNTPOINT> and contains a single +virtual file called F<FILENAME> (defaulting to F<nbd>). Reads and +writes to the virtual file or device are turned into reads and writes +to the NBD device. + +The NBD device itself can be local or remote and is specified by an +NBD URI (like C<nbd://localhost>, see L<nbd_connect_uri(3)>) or +various other modes. + +Use C<fusermount -u MOUNTPOINT> to unmount the filesystem after you +have used it. + +This program is similar in concept to L<nbd-client(8)> (which turns +NBD into F</dev/nbdX> device nodes), except: + +=over 4 + +=item * + +nbd-client is faster because it uses a special kernel module + +=item * + +nbd-client requires root, but nbdfuse can be used by any user + +=item * + +nbdfuse virtual files can be mounted anywhere in the filesystem + +=item * + +nbdfuse uses libnbd to talk to the NBD server + +=item * + +nbdfuse requires FUSE support in the kernel + +=back + +=head1 EXAMPLES + +=head2 Present a remote NBD server as a local file + +If there is a remote NBD server running on C<example.com> at the +default NBD port number (10809) then you can turn it into a local file +by doing: + + $ mkdir dir + $ nbdfuse dir nbd://example.com & + $ ls -l dir/ + total 0 + -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 nbd + +The file is called F<dir/nbd> and you can read and write to it as if +it is a normal file. Note that writes to the file will write to the +remote NBD server. After using it, unmount it: + + $ fusermount -u dir + $ rmdir dir + +=head2 Use nbdkit to create a file backed by a temporary RAM disk + +L<nbdkit(1)> has an I<-s> option allowing it to serve over +stdin/stdout. You can combine this with nbdfuse as follows: + + $ mkdir dir + $ nbdfuse dir/ramdisk --command nbdkit -s memory 1G & + $ ls -l dir/ + total 0 + -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 ramdisk + $ dd if=/dev/urandom bs=1M count=100 of=mp/ramdisk conv=notrunc,nocreat + 100+0 records in + 100+0 records out + 104857600 bytes (105 MB, 100 MiB) copied, 2.08319 s, 50.3 MB/s + +When you have finished with the RAM disk, you can unmount it as below +which will cause nbdkit to exit and the RAM disk contents to be +discarded: + + $ fusermount -u dir + $ rmdir dir + +=head2 Use qemu-nbd to read and modify a qcow2 file + +L<qemu-nbd(8)> cannot serve over stdin/stdout, but it can use systemd +socket activation. You can combine this with nbdfuse and use it to +open any file format which qemu understands: + + $ mkdir dir + $ nbdfuse dir/file.raw \ + --socket-activation qemu-nbd -f qcow2 file.qcow2 & + $ ls -l dir/ + total 0 + -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 file.raw + +File F<dir/file.raw> is in raw format, backed by F<file.qcow2>. Any +changes made to F<dir/file.raw> are reflected into the qcow2 file. To +unmount the file do: + + $ fusermount -u dir + $ rmdir dir + +=head1 OPTIONS + +=over 4 + +=item B<--help> + +Display brief command line help and exit. + +=item B<--fuse-help> + +Display FUSE options and exit. See I<-o> below. + +=item B<--command> CMD [ARGS ...] + +Select command mode. In this mode an NBD server can be run directly +from the command line with nbdfuse communicating with the server over +the server’s stdin/stdout. Normally you would use this with +C<nbdkit -s>. See L</EXAMPLES> above and L<nbd_connect_command(3)>. + +=item B<--fd> N + +Select file descriptor mode. In this mode a connected socket is +passed to nbdfuse. nbdfuse connects to the socket on the numbered +file descriptor. See also L<nbd_connect_socket(3)>. + +=item B<-o> FUSE-OPTION + +Pass extra options to FUSE. To get a list of all the extra options +supported by FUSE, use I<--fuse-help>. + +Some potentially useful FUSE options: + +=over 4 + +=item B<-o> B<allow_other> + +Allow other users to see the filesystem. This option has no effect +unless you enable it globally in F</etc/fuse.conf>. + +=item B<-o> B<kernel_cache> + +Allow the kernel to cache files (reduces the number of reads that have +to go through the L<libnbd(3)> API). This is generally a good idea if +you can afford the extra memory usage. + +=item B<-o> B<uid=>N B<-o> B<gid=>N + +Use these options to map UIDs and GIDs. + +=back + +=item B<-P> PIDFILE + +=item B<--pidfile> PIDFILE + +When nbdfuse is ready to serve, write the nbdfuse process ID (PID) to +F<PIDFILE>. This can be used in scripts to wait until nbdfuse is +ready. Note you mustn't try to kill nbdfuse. Use C<fusermount -u> to +unmount the mountpoint which will cause nbdfuse to exit cleanly. + +=item B<-r> + +=item B<--readonly> + +Access the network block device read-only. The virtual file will have +read-only permissions, and any writes will return errors. + +=item B<--socket-activation> CMD [ARGS ...] + +Select systemd socket activation mode. This is similar to +I<--command>, but is used for servers like L<qemu-nbd(8)> which +support systemd socket activation. See L</EXAMPLES> above and +L<nbd_connect_systemd_socket_activation(3)>. + +=item B<--tcp> HOST PORT + +Select TCP mode. Connect to an NBD server on a host and port over an +unencrypted TCP socket. See also L<nbd_connect_tcp(3)>. + +=item B<--unix> SOCKET + +Select Unix mode. Connect to an NBD server on a Unix domain socket. +See also L<nbd_connect_unix(3)>. + +=item B<-V> + +=item B<--version> + +Display the package name and version and exit. + +=back + +=head1 NOTES + +=head2 Loop mounting + +It is tempting (and possible) to loop mount the file. However this +will be very slow and may sometimes deadlock. Better alternatives are +to use either L<nbd-client(8)>, or more securely L<libguestfs(3)>, +L<guestfish(1)> or L<guestmount(1)> which can all access NBD servers. + +=head2 As a way to access NBD servers + +You can use this to access NBD servers, but it is usually better (and +definitely much faster) to use L<libnbd(3)> directly instead. To +access NBD servers from the command line, look at L<nbdsh(1)>. + +=head1 SEE ALSO + +L<libnbd(3)>, +L<nbdsh(1)>, +L<fusermount(1)>, +L<mount.fuse(8)>, +L<nbd_connect_uri(3)>, +L<nbd_connect_command(3)>, +L<nbd_connect_socket(3)>, +L<nbd_connect_systemd_socket_activation(3)>, +L<nbd_connect_tcp(3)>, +L<nbd_connect_unix(3)>, +L<libguestfs(3)>, +L<guestfish(1)>, +L<guestmount(1)>, +L<nbdkit(1)>, +L<nbdkit-loop(1)>, +L<qemu-nbd(8)>, +L<nbd-client(8)>. + +=head1 AUTHORS + +Richard W.M. Jones + +=head1 COPYRIGHT + +Copyright (C) 2019 Red Hat Inc. diff --git a/fuse/test-nbdkit.sh b/fuse/test-nbdkit.sh new file mode 100755 index 0000000..fe7279b --- /dev/null +++ b/fuse/test-nbdkit.sh @@ -0,0 +1,63 @@ +#!/usr/bin/env bash +# nbd client library in userspace +# Copyright (C) 2019 Red Hat Inc. +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +# Test nbdfuse + nbdkit. + +. ../tests/functions.sh + +set -e +set -x + +requires nbdkit --exit-with-parent --version +requires cmp --version +requires dd --version + +if ! test -r /dev/urandom; then + echo "$0: test skipped: /dev/urandom not readable" + exit 77 +fi + +pidfile=test-nbdkit.pid +mp=test-nbdkit.d +data=test-nbdkit.data +cleanup_fn fusermount -u $mp +cleanup_fn rm -rf $mp +cleanup_fn rm -f $pidfile $data + +mkdir -p $mp +$VG nbdfuse -P $pidfile $mp \ + --command nbdkit -s --exit-with-parent memory 10M & + +# Wait for the pidfile to appear. +for i in {1..60}; do + if test -f $pidfile; then + break + fi + sleep 1 +done +if ! test -f $pidfile; then + echo "$0: nbdfuse PID file $pidfile was not created" + exit 1 +fi + +dd if=/dev/urandom of=$data bs=1M count=10 +# Use a weird block size when writing. It's a bit pointless because +# something in the Linux/FUSE stack turns these into exact 4096 byte +# writes. +dd if=$data of=$mp/nbd bs=65519 conv=nocreat,notrunc +cmp $data $mp/nbd diff --git a/fuse/test-qcow2.sh b/fuse/test-qcow2.sh new file mode 100755 index 0000000..95f97b5 --- /dev/null +++ b/fuse/test-qcow2.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +# nbd client library in userspace +# Copyright (C) 2019 Red Hat Inc. +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +# The nbdfuse documentation describes how you can use nbdfuse + +# qemu-nbd to open qcow2 files. This claim is tested here. + +. ../tests/functions.sh + +set -e +set -x + +requires qemu-nbd --version +requires qemu-img --version +requires cmp --version +requires dd --version + +if ! test -r /dev/urandom; then + echo "$0: test skipped: /dev/urandom not readable" + exit 77 +fi + +pidfile=test-qcow2.pid +mp=test-qcow2.d +data=test-qcow2.data +qcow2=test-qcow2.qcow2 +cleanup_fn fusermount -u $mp +cleanup_fn rm -rf $mp +cleanup_fn rm -f $pidfile $data $qcow2 + +dd if=/dev/urandom of=$data bs=1M count=1 +qemu-img convert -f raw $data -O qcow2 $qcow2 + +mkdir -p $mp +$VG nbdfuse -r -P $pidfile $mp \ + --socket-activation qemu-nbd -f qcow2 $qcow2 & + +# Wait for the pidfile to appear. +for i in {1..60}; do + if test -f $pidfile; then + break + fi + sleep 1 +done +if ! test -f $pidfile; then + echo "$0: nbdfuse PID file $pidfile was not created" + exit 1 +fi + +cmp $data $mp/nbd diff --git a/run.in b/run.in index 83c92a7..599752d 100755 --- a/run.in +++ b/run.in @@ -51,6 +51,7 @@ s="$(cd @abs_srcdir@ && pwd)" b="$(cd @abs_builddir@ && pwd)" # Set the PATH to contain all libnbd binaries. +prepend PATH "$b/fuse" prepend PATH "$b/sh" export PATH diff --git a/sh/nbdsh.pod b/sh/nbdsh.pod index 0037dc3..c1d93ba 100644 --- a/sh/nbdsh.pod +++ b/sh/nbdsh.pod @@ -97,6 +97,7 @@ Display the package name and version and exit. L<libnbd(3)>, L<libnbd-security(3)>, +L<nbdfuse(1)>, L<qemu-img(1)>. =head1 AUTHORS -- 2.23.0