Remote Virtual Disk Control (RVDCTL) Protocol Specification by L. W. Allen, J. H. Saltzer, and P. Prindeville version of August 25, 1986 Overview The Remote Virtual Disk Control (RVDCTL) protocol supplies a Remote Virtual Disk server with both operating instructions and information about its configuration. An RVD server process comes into existence with no knowledge of the physical configuration of the system in which it is embedded or the logical configuration of the (possibly already existing) virtual disk packs it is to manage. By supplying this information via a network connection instead of from files on the server host, it becomes possible to administer all aspects of server operation remotely. This description assumes that the reader is already familiar with the basic concepts and terminology of the Remote Virtual Disk system, as outlined in the Remote Virtual Disk System Overview. There are four scenarios in which the RVDCTL protocol is used: 1. Initialization. The first step after creating an RVD server process is to send it, using the RVDCTL protocol, a description of the physical and virtual disk configuration it is to manage. Because RVDCTL is a network protocol, the permanent data base that contains this state description may be managed on a machine different from that of the server. 2. Permanent changes. When permanent changes to the physical and virtual disk pack configuration are desired, a management program both updates the permanent data base and sends to the server the same updates, again using the RVDCTL protocol. 3. Temporary changes, for maintenance. A client that can supply an operations password can invoke certain maintenance functions of the RVDCTL protocol, such as changing the logging level, shutting down the server, posting a message, or forcing off certain clients. For operations purposes, it is possible to invoke any of the update functions normally associated with permanent changes. Although a running RVD server would operate on the updated basis, if that server process were killed and recreated, such temporary changes would be forgotten, because the new server would receive its initialization from the permanent data base, 4. Client use. RVD clients use the RVDCTL protocol for certain client-server interactions such as flushing out old spinups, and to inquire about current operations. There are several programs that invoke the RVDCTL protocol. Corresponding to the second scenario, above, is a data base management program named vddb(8), which operates as follows: - The database maintainer (human) runs the data base management program, which prompts for and validates input. - The data base management program updates the disk files containing the permenent data base. - The data base management program opens a control connection to the currently-running server and sends the server the updated information. - The server modifies its state tables according to the requests. - The server acknowledges the modification. For simplicity, the data base management program stores its permanent data base in the form of a sequence of already-formatted protocol messages, so the initialization scenario is accomplished simply by sending a copy of the permanent data base to the server on the RVDCTL network connection. A program named rvdsend(8) does this job. The programs that perform the third and fourth scenarios are commands that can be run on any client (perhaps on behalf of another client) to invoke one or more specific RVDCTL functions at the server directly, without involving the database program. Because most control operations for the RVD server require transferring only small amounts of data, and one wants to be able to implement servers on machines that do not provide a full TCP, the control protocol is UDP-based. It is a simple, lock-step, idempotent, message-response protocol. For all the control functions of interest, the control data fit into a single packet, which further simplifies the protocol. Idempotent means that if a client receives no response to a request (and is therefore unsure of whether or not the server acted on it,) it is always safe to resend the same request, because by design successive repetitions of all RVDCTL operations have no ill effects. The RVDCTL protocol carries very little traffic in comparison with the RVD protocol, so ease of construction and debugging is therefore of higher priority than performance. So that the control connection can handle operations of varying parameter requirements, to avoid the need to design a new packet format every time a new control function is added, and so that a single source implementation can apply to machines of different byte order, all data is transmitted as ASCII strings. For simplicity in parsing, arguments are transmitted in the format "keyword=value". This approach also makes RVDCTL packets self-explanatory when encountered during monitoring or auditing. Syntax of the RVDCTL protocol: :== :== operation= | success= | failure= error= :== | :== = :== :== is a string of network ASCII characters, terminated by a separator character. The separator characters are space, tab, newline, carriage return, and formfeed. One or more separators must appear between operands. Separators may be included in strings by quoting them. The quote character is the backslash '\'; a backslash may be included in an string by doubling it: '\\'. Also, to include an equals sign '=' in a string, it must be quoted. The particular keywords used depend on the operation being invoked. The keywords 'operation', 'password', 'nonce' 'success', 'failure' and 'error' are universal. 1. The 'operation' keyword must be the first keyword in each request packet. Its value is the name of the requested operation. 2. The 'password' keyword supplies a password operand if the operation requires one. (There are three kinds of passwords. The operations password authorizes shutdown, logging, and physical configuration management. The administrative password authorizes allocation and deallocation of virtual disks. Individual pack passwords authorize usage of those packs.) 3. The 'nonce' keyword appears in every request, with a value chosen * by the requester to be different from any other request for which a * late response might still arrive. Every response contains a copy of * the nonce of the request to which it responds. 4. The 'success' keyword must be the first keyword in a response to a successful request. Its value is the name of the operation performed. 4. The 'failure' keyword must be the first keyword in a response to an unsuccessful request. Its value is the name of the operation that failed. It may be accompanied with an 'error=' operand describing the error which occurred. The value of the 'error' keyword is a human-readable string describing the error which occurred. Except for 'operation', 'success' and 'failure', each of which must be the first keyword in a message, the order of operands in a message is unimportant. Where a number is called for, it is represented in the operand value string as an ASCII decimal integer. Where an Internet Protocol (IP) Address is called for, it is represented in the operand value string as "A.B.C.D", in network standard ASCII decimal form. Where a mode is called for, it is represented in the operand value string as an ASCII decimal number coded in the following way: 1 = read-only spinups allowed 2 = shared spinups allowed (not currently implemented) 4 = exclusive spinups allowed in any sum desired; the value 0 means no spinups allowed. Port: The RVDCTL protocol operates on UDP port 531. Operations: [Note: operations and operands marked with an asterisk to the right * have not yet been implemented.] 1. Add a physical device partition to the set of partitions managed by the RVD server. operation=add_physical Required operands: password The operations password for the RVD server. filename Path name of the device to be managed as a physical partition. blocks The number of 512-byte sectors in this physical partition. Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations and administration access lists. If this operand is used the "password=" operand must still be provided but no password value is necessary. The device need not be a real physical disk; any device (e.g., a file) that behaves like a raw disk partition will work equally well. If the server finds it is unable to open the physical device it * marks the physical device as "disused", and returns an error. (See disuse_physical.) Note that the add_physical operation is normally invoked as part of updating the permanent data base that describes the server configuration. If add_physical is invoked without a data base update, the next time the server is shut down the change made by the add_physical operation will be forgotten. 2. Delete a physical device partition from the set of partitions * managed by the RVD server. operation=delete_physical Required operands: password The operations password for the RVD server. filename Path name of the device to be managed as a physical partition. Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations and administration access lists. If this operand is used the "password=" operand must still be provided but no password value is necessary. If there are any virtual disk packs allocated on this physical device, delete_physical returns an error response, and does not delete the device. Note that the delete_physical operation is normally invoked as part of updating the permanent data base that describes the server configuration. If delete_physical is invoked without a data base update, the next time the server is shut down the change made by the delete_physical operation will be forgotten. 3. Stop using a physical disk partition. * operation=disuse_physical Required operands: password The operations password for this RVD server. physical The pathname of the device partition to be disused. Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list. If this operand is used the "password=" operand must still be provided but no password value is necessary. The disuse_physical operation allows an operator to take a partition out of use, for example because the disk is getting hard errors. (The server may, on its own, place a partition that is getting errors in disused mode.) Add_virtual and delete_virtual operations may be executed on a disused partition. Attempts to spinup packs that are located on a disused partition receive the error response "pack temporarily unavailable." The server continues to maintain records of existing connections and to allow spindowns, but attempts to read or write a previously spunup pack receive an error packet containing the error code "pack temporarily unavailable." 4. Try to use a physical disk partition. * operation=use_physical Required operands: password The operations password for this RVD server. physical The pathname of the device partition to be used. Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list. If this operand is used the "password=" operand must still be provided but no password value is necessary. If a physical partition is currently disused, this operation puts the partition back into service. If the physical partition does not exist or is already in use, use_physical returns an error. 5. Allocate a virtual disk pack. operation=add_virtual Required operands: password The administrative password for this RVD server. physical The pathname of the device partition this virtual disk pack is to be on. name The name of this virtual disk pack (n.b., upper and lower case are distinguished.) packid The unique id of this pack on this server. * owner The name of this virtual disk pack's owner. rocap The read-only mode password (may be null). excap The exclusive mode password (may be null). shcap The shared mode password (may be null). modes The allowable modes this virtual disk pack may be spun up in. offset The offset, in blocks, of this virtual disk pack from the start of the physical partition. blocks The number of 512-byte blocks in this virtual disk. Optional operands: ownhost Internet address of the owning host of this virtual disk pack. If none is supplied, the disk is assumed to not have an owning host. auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations and administration access lists. If this operand is used the "password=" operand must still be provided but no password value is necessary. Note that the add_virtual operation is normally invoked as part of updating the permanent data base that describes the server configuration. If add_virtual is invoked without a data base update, the next time the server is shut down the addition made by add_virtual operation will be forgotten. 6. Deallocate a virtual disk pack operation=delete_virtual Required operands: password Administrative password. Optional operands: packid The unique identifier of the virtual disk * pack to be deallocated name The name of the virtual disk pack to be deallocated. auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations and administration access lists. If this operand is used the "password=" operand must still be provided but no password value is necessary. One of the operands {packid, name} must be present. If both are present, they must refer to the same pack. Note that the delete_virtual is normally invoked as part of updating the permanent data base that describes the server configuration. If delete_virtual is invoked without a data base update, the next time the server is shut down the deletion made by delete_virtual operation will be forgotten. 7. Modify the definition of a virtual disk pack. operation=modify_virtual Required operands: password Administrative password. name the name of the virtual disk pack whose description is to be modified. Optional operands (any operand present supersedes the value previously supplied by add_virtual or modify_virtual of the corresponding parameter for this virtual disk pack): packid The unique identifier of this pack. If * provided, this operand is used to identify pack to be modified, and the name operand is taken to be a new pack name. owner The name of this virtual disk pack's owner. rocap The read-only mode password excap The exclusive mode password shcap The shared mode password modes The allowable modes this virtual disk pack may be spun up in, as an ASCII decimal number. blocks The number of 512-byte blocks in this virtual disk. Must be <= the current number of blocks on this disk. In general, changing a disk's size is a bad idea, especially if it is currently in use. ownhost Internet address of the owning host of this disk. auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations and administration access lists. If this operand is used the "password=" operand must still be provided but no password value is necessary. Note that the modify_virtual operation is normally invoked as part of updating the permanent data base that describes the server configuration. If modify_virtual is invoked without a data base update, the next time the server is shut down the changes made by the modify_virtual operation will be forgotten. 8. Exchange the names of two virtual disk packs. operation=exchange_names Required operands: name1 Desired name for the first virtual disk pack packid1 Unique identifier of first pack password1 The exclusive mode password of the first virtual disk pack. name2 Desired name for the second virtual disk pack. packid2 Unique identifier of second pack password2 The exclusive mode password of the second virtual disk pack. Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list and, if he is not on that list, the pack owner and exclusive mode lists for both packs. If this operand is used the "password1=" and "password2=" operands must still be provided but no password value is necessary. The operands name1 and name2 must be the names presently associated with the two packs. Success for this operation means that those two names are now associated with the packs in the order requested, whether or not they were before the operation. This operation is used as part of an update procedure, in which two copies of a library virtual disk pack are maintained. One copy is normally spun up by clients in read-only mode; the other is the "maintenance" copy, to which the owner makes changes. Once a consistent set of changes are ready for release, the owner exchanges the names of the packs. Other users can then spin the pack down and back up again by name to get the new copy. If the server shuts down and restarts, clients that have temporarily cached the packid can respin up the old pack by packid, to complete their session without being forced prematurely to switch to the new library. Note that the exchange_names operation is normally invoked as part of updating the permanent data base that describes the server configuration. If exchange_names is invoked without a data base update, the next time the server is shut down the exchange_names operation will be forgotten. 9. Force a virtual disk pack to be spun down. operation=spindown_virtual Required operands: name The name of the virtual disk pack to be forced down. password The exclusive mode password of the virtual disk pack to be forced down. Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list and the exclusive mode access list for this pack. If this operand is used the "password=" operand must still be provided but no password value is necessary. This operation is normally used by the owner of a virtual disk pack that was spun up on a machine that crashed. It forces the specified virtual disk pack to be spun down from all the machines that have it spun up. 10. Force all virtual disk packs of a given client at this server to be spun down. operation=spindown_host Required operands: name the Internet address of the client whose disk packs are to be forced down. Optional operands: password If the spindown_host request was not sent from the client whose disks are to be spun down, the operations password must be supplied. auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list. This operation has two uses: a) it should appear in a UNIX client's /etc/rc file, or a DOS client's autoexec.bat file, so that when a host recovers from a crash, all its previously spunup virtual disk packs are spun down. This spindown insures that the server state agrees with the client state. b) a operator can use this operation to force down the virtual disks of a client which has crashed and which may be down for some time. 11. Display all spinups involving a virtual disk pack, or a client. operation=display_virtual Required operands (exactly one of the following must be present): name the name of a virtual disk pack. If present, display_virtual returns a list of all the spinups of this disk pack. These are the spinups that would be forced down if a spindown_virtual operation naming this pack were performed. host the IP address of a client. If present, display_virtual returns a list of all the spinups of this client. These are the spinups that would be forced down if a spindown_host operation naming this client were performed. Optional operands: start= An ASCII decimal integer giving the offset of the first spinup description wanted. This operand is normally supplied if a previous invocation of display_virtual contained the response "more=true". password If the display_virtual operation requests information about a client different from the one making the request, the operations password must be supplied. auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list. This operation returns a success packet containing an ASCII text string describing the spinups (host/drive number pairs) of this virtual disk. The response packet contains: success=display_virtual number= connections= more=true (optional response) is the number of currently active spinups for this virtual disk pack or client. is a canonicalized string, with one line per spinup, containing as many spinup descriptions as will fit in one UDP packet. Each line is a collection of space-separated tokens, as follows: pack=library host=18.72.0.5 drive=9 mode=4 Since the string is canonicalized, all spaces and CRLF sequences are quoted. If there were more spinup descriptions than would fit in a single packet, the response operand "more=true" will appear. 12. Log statistics of external interactions. operation=log_external_statistics Required operand: password The operations password Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list. If this operand is used the "password=" operand must still be provided but no password value is necessary. Dump into the log file all statistics kept by the rvd server concerning inacteractions with clients--number of packets exchanged, disk operations, etc.) 13. Log all statistics operation=log_all_statistics Required operand: password The operations password Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list. If this operand is used the "password=" operand must still be provided but no password value is necessary. Dump into the log file all statistics kept by the rvd server. 14. Shut down server operation=shutdown Required operands: password The operations password Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations and shutdown access lists. If this operand is used the "password=" operand must still be provided but no password value is necessary. Log all statistics, then perform a clean shutdown of the server. 15. Change log level operation=log_level Required operands: password The operations password level New log level as a hex number (N.B., not decimal.) Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list. If this operand is used the "password=" operand must still be provided but no password value is necessary. Change which events are logged; see specification of the RVD protocol for definition of log levels. 16. Truncate log operation=log_truncate Required operands: password The operations password Truncate the log file to keep it from growing too large. [In the BSD 4.3 UNIX (UNIX is a trademark of AT&T) implementation of RVD, logging is done with the UNIX logging system (syslogd), so this operation has no effect.] 17. Allow spinups operation=allow_spinups Required operands: password The operations password, for a physical device, or the exclusive mode pack password, for a single virtual pack. mode The mode of allowed spinups. Optional operands: physical Path name of the device partition to which this mode setting applies. (If absent, the mode applies to all partitions managed by this server.) name The name of a virtual disk pack to which this mode setting applies. auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list. If this operand is used the "password=" operand must still be provided but no password value is necessary. Response operand: oldmode The spinup mode that was formerly allowed for this partition or virtual pack. This operation is used to prevent or allow further spinups of a single virtual pack, or all the virtual packs on a given device partition of this RVD server; it has no effect on spinups already in force. When a server first comes up it allows no spinups (mode=0), so an invocation of allow_spinups is required as part of starting a server. A separate allowed spinup mode value is maintained for each pack and for each partition; the actual modes permitted for a pack are given by the logical AND of the mode value for the pack and the mode value for the partition on which it is located. The server rejects spinups that would be allowed by the static pack description but that are prevented by the current setting of allow_spinups with a distinct error code indicating temporary unavailability. Usage scenarios: If a server is to be dumped, one might allow only read spinups during the dump; if a server is to be taken down one might sometime earlier allow no new spinups. The maintainer of a library disk pack that needs to be updated might first allow no spinups, then after a period of time adequate for most clients to finish their sessions, do a spindown_virtual to get rid of any remaining spinups. 18. Post an operations message. operation=set_message Required operands password The operations password message= The (canonicalized) message replaces any previous operations message. If is null, any previous message is cleared. The content of the message is limited to 400 bytes, and is network ASCII (lines terminated with canonicalized CRLF's). Optional operands: auth The Kerberos authenticator. This is used to verify a user name. That user is then checked against the operations access list. If this operand is used the "password=" operand must still be provided but no password value is necessary. This operation, together with the next one, allows an operator to post a message (e.g., "server going down at 5:00 p.m. for preventive maintenance") for clients of an RVD server. 19. Get the operations message. operation=get_message (no required or optional operands) Response operands: success=get_message message= is a canonicalized string of network ascii to be displayed as an operations message. If there is no current operations message, is null. (Note that in either case is terminated by an operand separator.) This operation would normally be invoked by a client as part of bringing up a system that uses RVD and also whenever spinning up a virtual disk pack. 20. Change a user password. * operation=change_password Required operands packname The name of the virtual disk pack whose password is to be changed. mode The spinup modes for which a new password is being supplied. If more than one mode is specified, the operation will be rejected unless the old passwords for the several modes are all the same as the old_password operand. old_password The current password for this pack and mode; a null string if there is no current password. new_password The new password; a null string if there is to be no password. Note that this function is not intended for direct use by a client, but rather for use by the database update system; if used by a client without also updating the database, the password will be restored to its old value the next time the RVD server is restarted. 21. Return a list of active virtual packs operation=display_active Optional operands: filename Path name of device partition for which a list of active virtual packs is wanted. If omitted, a list of all active virtual packs is returned. start= A number giving the offset of the first information line wanted. This operand is normally supplied if the previous invocation of display_active included the response operand "more=true". Response operand: number= activity= more=true (optional response) is the number of currently active packs on this partition or, if no partition was specified, on this server. is a single canonicalized netascii string containing one line of information for each active virtual pack. A typical line looks like: partition=/dev/ra0g pack=library mode=1 connections=5 idle=1721 If there were more activity descriptions than would fit in a single packet, the response operand "more=true" will appear. Idle time is measured in seconds since most recent access. Note that the idle time is purely an activity hint, to determine whether or not a pack that appears to be spun up is actively in use. It is maintained by the server only to a rough approximation. 22. Obtain server load statistics operation=get_load Response: load= is a canonicalized netascii string containing load statistics ready for display. 24. Change authorization for operations and administrative operations. operation=require_authorization (no required or optional operands) When an rvd server begins operation, it accepts rvd control protocol requests only from the same host on which it is operating, and it does not require operations or administrative passwords. (Starting without passwords allows automating initialization without the need to store those passwords in clear form.) The require_authorization operation causes the server to read operations and administrative passwords from a file in the file system of the server's host. After require_authorization is executed all operations listed above as requiring either an administrative or operations password do actually require them. Whenever require_authorization is invoked, the rvd server reinitializes its copy of the operations and administrative passwords from /etc/rvdauthor. There are two scenarios of use of require_authorization. The first is at system initialization time: - start server - send initializing control sequences, if any - send require_authorization - await success of require_authorization - declare initialization successful. The second scenario is to change the operations or administrative passwords. - modify file containing operations and maintenance passwords. - send require_authorization