farsight is a client/server application that allows users to implement block devices without the need for kernel modules by extending a very simple interface.
As with most python packages, it suffices to call the setup script:
python3 setup.py installAfterwards, we may use the client and server modules within the 'farsight' package. First, we need to provide configuration files for both. The chosen format is TOML, because of its simplicity and portability.
The client must specify the sections: "nbd", "server" and "backend".
These are low-level parameters to use in the underlying NBD protocol. This section is currently comprised of 2 parameters: "file" and "blocksize".
The "file" parameter specifies which of the "/dev/nbd" block devices should be bound to a backing storage (described later in this document). The device must not be in use at the time the client is started.
The "blocksize" parameter indicates the size in bytes of the block for the device, as the Linux kernel would see it. The kernel performs operations within the block device in units of this size. (Note, however, that across the network, the kernel always uses a page for granularity).
This section specifies the needed parameters to connect to a server. Namely, the "address" and "port" keys are used to uniquely identify the server. We support both IPv4 and IPv6 addresses.
This section describes which backend will be used by the server to back a block device. Each backend has its own set of parameters, described later in this document. The only required parameter is "name" which is read by the server to determine which of the supported backends will be used.
The server must define the aptly named "server" section which will define the address and port where it will listen for connections, and it should have one section per supported backend.
In addition to the "address" and "port" parameters which define where the server will be listening for incoming clients, there's an additional parameter called "max_errors", which specifies how many invalid requests per client the server will tolerate before disconnecting said client.
By themselves, the client and server don't do much unless they agree on a backend to use. At the time of this writing, farsight only supports the "rbd" backend, which needs to be configured by both the client and server.
In order to use the RBD backend, the server must have the necessary libraries included. They can be installed by the system's package manager. For example, on Ubuntu, you may run something like this:
apt install python3-rados python3-rbdFor more information, see here: https://docs.ceph.com/en/latest/rados/api/python/ https://docs.ceph.com/en/latest/rbd/api/librbdpy/
Note that if those libraries aren't present, the server won't be able to use the RBD backend, but it will still be able to boot up and run.
When using this backend, the client must set the "name" key to "rbd". In addition, it must set the "pool" and "image" keys to specify which image to use in a particular pool.
To support this backend, the server must set the "ceph_conf" which specifies the path of a Ceph configuration file, which is typically found in "/etc/ceph/ceph.conf" and includes (among other things) the monitor hosts and the needed keyrings to access the cluster. Additionally, the "ceph_user" key must be set to specify the username to use when accessing the cluster.
In the "examples" directory there are 2 files corresponding to the client and server configuration to support an RBD-backed block device.
Before attempting to use the application, the client must ensure that it has
the nbd module up and running. This can be done by calling:
modprobe nbdAfterwards, the files /dev/nbdX should be visible.
Furthermore, if using udev, the following rule should be added in
order to prevent NBD requests from lingering indefinitely:
$ cat << EOF >> /etc/udev/rules.d/97-nbd-device.rules
# Disable inotify watching of change events for NBD devices
ACTION=="add|change", KERNEL=="nbd*", OPTIONS:="nowatch"
EOF
udevadm control --reload-rules
udevadm triggerWith the application installed and configured, we can now use the client and server:
python3 -m farsight.client <path_to_config_file>
python3 -m farsight.server <path_to_config_file>Assuming everything goes well, both applications will block indefinitely when running: the client to back a block device with the configured backend and the server to handle incoming clients. They both can be interrupted by signals to stop their execution.
The client will most likely need root permissions, as it needs to open and manage an NBD block device. Once the client has been connected, the corresponding device can be opened for read/write, and its contents will be backed as specified by the backend.