1NBD README
2==========
3
4Welcome to the NBD userland support files!
5
6This package contains nbd-server and nbd-client.
7
8To install the package, download the source and do the normal
9`configure`/`make`/`make install` dance. You'll need to install it on both the
10client and the server. Note that released nbd tarballs are found on
11[sourceforge](http://sourceforge.net/projects/nbd/files/nbd/).
12
13For compiling from git, do a checkout, install the SGML tools
14(docbook2man), and then run './autogen.sh' while inside your checkout.
15Then, see above.
16
17Contributing
18------------
19
20If you want to send a patch, please do not open a pull request; instead, send
21it to the
22[mailinglist](https://lists.debian.org/nbd)
23
24Using NBD
25---------
26
27NBD is quite easy to use. First, on the client, you need to load the module
28and, if you're not using udev, to create the device nodes:
29
30    # modprobe nbd
31    # cd /dev
32    # ./MAKEDEV nbd0
33
34(if you need more than one NBD device, repeat the above command for nbd1,
35nbd2, ...)
36
37Next, write a configuration file for the server. An example looks like
38this:
39
40    # This is a comment
41    [generic]
42        # The [generic] section is required, even if nothing is specified
43        # there.
44        # When either of these options are specified, nbd-server drops
45        # privileges to the given user and group after opening ports, but
46        # _before_ opening files.
47        user = nbd
48        group = nbd
49    [export1]
50        exportname = /export/nbd/export1-file
51        authfile = /export/nbd/export1-authfile
52        timeout = 30
53        filesize = 10000000
54        readonly = false
55        multifile = false
56        copyonwrite = false
57        prerun = dd if=/dev/zero of=%s bs=1k count=500
58        postrun = rm -f %s
59    [otherexport]
60        exportname = /export/nbd/experiment
61        # The other options are all optional
62
63The configuration file is parsed with GLib's GKeyFile, which parses key
64files as they are specified in the Freedesktop.org Desktop Entry
65Specification, as can be found at
66<http://freedesktop.org/Standards/desktop-entry-spec>. While this format
67was not intended to be used for configuration files, the glib API is
68flexible enough for it to be used as such.
69
70Now start the server:
71
72    nbd-server -C /path/to/configfile
73
74Note that the filename must be an absolute path; i.e., something like
75`/path/to/file`, not `../file`. See the nbd-server manpage for details
76on any available options.
77
78Finally, you'll be able to start the client:
79
80    nbd-client <hostname> -N <export name> <nbd device>
81
82e.g.,
83
84    nbd-client 10.0.0.1 -N otherexport /dev/nbd0
85
86will use the second export in the above example (the one that exports
87`/export/nbd/experiment`)
88
89`nbd-client` must be ran as root; the same is not true for nbd-server
90(but do make sure that /var/run is writeable by the server that
91`nbd-server` runs as; otherwise, you won't get a PID file, though the
92server will keep running).
93
94There are packages (or similar) available for most current operating
95systems; see the "Packaging status" badge below for details.
96
97For questions, please use the [nbd@other.debian.org](mailto:nbd@other.debian.org) mailinglist.
98
99Badges
100======
101
102[![Download Network Block Device](https://img.shields.io/sourceforge/dm/nbd.svg)](https://sourceforge.net/projects/nbd/files/latest/download)
103[![Coverity Scan Build Status](https://scan.coverity.com/projects/1243/badge.svg)](https://scan.coverity.com/projects/1243)
104[![CII badge](https://bestpractices.coreinfrastructure.org/projects/281/badge)](https://bestpractices.coreinfrastructure.org/projects/281)
105[![Travis](https://img.shields.io/travis/NetworkBlockDevice/nbd.svg)](https://travis-ci.org/NetworkBlockDevice/nbd)
106
107[![Packaging status](https://repology.org/badge/vertical-allrepos/nbd.svg)](https://repology.org/metapackage/nbd)
108