OCFS2 Control Daemon Client Protocol
The ocfs2_controld daemon listens to clients for requests to mount and unmount filesystems. The gfs_controld had a network protocol for clients that was pretty much hard and fast. This document describes a protocol that fits ocfs2.
At first, I wanted to come up with a robust network protocol. You know, netstrings and the like. But I don't think I care enough. I'm going to follow their basic 256-byte packet scheme.
The Packet
All messages are a 256 byte packet. This packet size is controlled by the OCFS2_CONTROLD_MAXLINE define in ocfs2_controld.h. This allows all sends and receives to merely expect 256 bytes of payload.
The payload is a NUL terminated utf8 string. Thus, the maximum string is actually 255 ASCII characters. All data beyond the first NUL is currently unused.
Request Syntax
All requests begin with the request name. It is all capitals. Arguments to the request are separated by spaces. Spaces in an argument are currently not allowed, with the exception of the last argument. I'd probably go with urlencoding if I ever care to relax that requirement. The currently know requests are:
MOUNT - Request to mount a volume. This tells ocfs2_controld to join the specified group.
fstype - The filesystem type. Currently only ocfs2 is allowed.
uuid - The uuid of the filesystem. This is used as the name of the group to join.
cluster - The cluster to connect to.
device - The device the filesystem resides on.
mountpoint - The local directory where the filesystem is to be mounted. ocfs2_controld keeps track of multiple mounts for a particular filesystem.
MRESULT - Result of the kernel mount. This tells ocfs2_controld how the kernel side of mounting fared.
fstype - The filesystem type. Currently only ocfs2 is allowed.
uuid - The uuid of the filesystem being moounted. This tells ocfs2_controld which filesystem has completed mounting.
result - The return code from the mount(2) system call.
mountpoint - The local directory where the filesystem was being mounted. This differentiates multiple mountpoints mounting at the same time.
UNMOUNT - Request to unmount a volume. This tells ocfs2_controld to leave the specified group.
fstype - The filesystem being unmounted. Currently only ocfs2 is allowed.
uuid - The uuid of the filesystem being unmounted. This is used as the name of the group to leave.
mountpoint - The local directory where the filesystem is mounted.
LISTFS - List the filesystems managed by ocfs2_controld
fstype - The filesystem type. Currently only ocfs2 is allowed.
cluster - The cluster to check.
LISTMOUNTS - List the mountpoints for a given filesystem.
fstype - The filesystem type. Currently only ocfs2 is allowed.
uuid - The uuid of the filesystem being listed.
LISTCLUSTERS - List clusters the daemon is connected to.
DUMP - Dump the control daemons debug buffer.
Response Syntax
All requests receive a status response. The status response message looks like this:
STATUS
errno - The result as an errno value. 0 means success.
error-string - An error string containing any detailed information. It must fit within the packet length.
In addition, list requests receive the list before they receive status. First comes the item count, then each item, and finally a status message.
ITEMCOUNT
count - The number of items in the list. A positive integer.
ITEM
item - The item text. For LISTFS this is a uuid, for LISTMOUNTS this is a mountpoint, for LISTCLUSTERS this is the name of the cluster.
The Mount Protocol
- The client sends a MOUNT request.
- If this is the first mount of a filesystem, the daemon will try to join the group.
- If the join is successfull, a STATUS of 0 is returned.
- If the join fails, a STATUS error is returned.
Else if this filesystem is already mounted, the daemon will record the new mountpoint and return a STATUS of EALREADY.
If the client receives a STATUS that is not 0 or EALREADY, it fails the mount.
- If this is the first mount of a filesystem, the daemon will try to join the group.
The client calls mount(2) to perform the actual kernel mount.
- If the kernel mount succeeds, the client sends a MOUNT_RESULT request with a result of 0.
- The daemon will return a STATUS of 0.
- Else if the kernel mount fails, the client sends a MOUNT_RESULT request with the error.
- If this was an additional mount, the daemon removes that entry and returns its STATUS.
- Else ff this was a first mount, the daemon attempts to leave the group.
- If the leave is successful, a STATUS of 0 is returned.
- Else if the leave fails, a STATUS error is returned.
- If the kernel mount succeeds, the client sends a MOUNT_RESULT request with a result of 0.
The Unmount Protocol
The client unmounts the filesystem via umount(2).
- The client sends an UNMOUNT request.
- If this is the last mountpoint for this filesystem, the daemon will try to leave the group.
- The daemon will return a STATUS message once it has exited the group or failed to do so.
The List Protocol
- The client sends a LISTFS, LISTMOUNTS or LISTCLUSTERS message.
- If the appropriate mountgroup exists, the daemon sends an ITEMCOUNT response.
- The daemon sends one ITEM mesasge per item.
- The daemon sends a STATUS of 0.
- Else the daemon sends a STATUS with the error.
- If the appropriate mountgroup exists, the daemon sends an ITEMCOUNT response.
The Dump Protocol
- The client sends a DUMP message.
- The daemon calculates how many protocol packets will be required to transfer the dump buffer and sends this as an ITEMCOUNT response.
- The daemon sends one ITEM message per packet.
- The daemon sends a STATUS of 0.
- The client concatenates every packet in the list to obtain the full debug buffer.