search

abligh / gonbdserver

And NBD server written in golang
MIT License
81 stars 22 forks source link

readme

gonbdserver Build Status GoDoc GitHub release

gonbdserver is an NBD server written in Go. Its purpose is not to be especially performant, but rather to act as a simple demonstration of the implementation of the NBD protocol. That said, where tested it appears to be at least as fast as the reference nbdserver implementation.

Features

NBD Experimental Extensions Implemented

Invocation

Invocation is very easy. It takes a minimum number of command-line flags. Most of the configuration is within the configuration file.

$ ./gonbdserver --help
Usage of ./gonbdserver:
  -c string
        Path to YAML config file (default "/etc/gonbdserver.conf")
  -f    Run in foreground (not as daemon)
  -p string
        Path to PID file (default "/var/run/gonbdserver.pid")
  -s string
        Send signal to daemon (either "stop" or "reload")

By default gonbdserver runs as a daemon. You can use -f to make it run in the foreground. If you are running on Linux and want to run from init, you may wish to consider using start-stop-daemon with the -b flag, and invoking gondbserver with the -f flag, as start-stop-daemon is probably better at dealing with the many possible failure modes.

When running in foreground mode, the pid file is not used, and -s is irrelevant.

Note that to use the -s option, it is necessary to specify the -c and -p options that you used in launching the daemon.

Signals

Configuration

Configuration is provided through a YAML file which by default lives at /etc/gonbdserver.conf, though this can be specified using the -c option.

An example of a configuration is set out below:

servers:
- protocol: tcp                  # A first server, using TCP
  address: 127.0.0.1:6666        # on port 6666
  exports:                       # It has two exports
  - name: foo                    # The first is named 'foo' and
    driver: file                 # Uses the 'file' driver
    path: /tmp/test              # This uses /tmp/test as the file
    workers: 4                   # Use 4 workers
  - name: bar                    # The second export is called 'bar'
    readonly: true               # This is readonly
    driver: rbd                  # And uses the (currently imaginary) rbd driver
    image: rbdbar                # on this rados block device name
    tlsonly: true                # require TLS on this device
  tls:                           # use the following certificates
    keyfile: /path/to/server-key.pem
    certfile: /path/to/server-cert.pem
    cacertfile: /path/to/ca-cert.pem
    servername: foo.example.com  # present the server name as 'foo.example.com'
    clientauth: requireverify    # require and verify client certificates
- protocol: unix                 # Another server uses UNIX
  address: /var/run/nbd.sock     # served on this socket
  exports:                       # it has one export
  - name: baz                    # named bar
    driver: file                 # using the file driver
    path: /tmp/baz               # on this file
    sync: true                   # open with O_SYNC
  disablenozeroes: true          # disable nozereos for back compatibility
logging:                         # log to
  syslogfacility: local1         # local1

A description of the configuration file's sections is set out below

Top level

The top level of the configuration file consists of the following sections:

server items

Each server item specifies a TCP port or unix socket that is listened to for new connections.

Each server item consists of the following:

export items

Each export item represents an export (i.e. an NBD disk) to be served by the server. Each export is served by a driver, and the drivers parameters (which are specific to the driver) may be intermingled with the export parameters.

Each export item consists of the following (common to all drivers):

The file driver reads the disk from a file on the host OS's disks. It has the following options:

The aiofile driver reads the disk from a file on the host OS's disks using AIO (available on Linux only). This driver is experimental; do not use it in production. It has the following options:

The rbd driver reads the disk from Ceph. It relies on your ceph.conf file being set up correctly, and has the following options:

Note the Ceph driver is almost entirely untested

tls item

The tls item is used to enable TLS encryption on a server. If TLS is enabled on a server, the exports will be available over TLS. To make individual exports available only over TLS, add tlsonly: true to the export

logging item

The logging item controls logging. There are three types of logging supported:

The logging item consists of the following:

Licence

The code is licensed under the MIT licence.