multifile(1) FreeBSD General Commands Manual multifile(1) NAME multifile – multiplexing file server SYNOPSIS multifile -t ⟨tlsconfigfile⟩ -r ⟨rootdir⟩ DESCRIPTION Multifile is a multiplexing file server with Transport Layer Security. Mutifile delivers up to 255 multiplexed streams of file data per connection. You can turn off multiplexing to conserve resources. A companion library, libmultifile(3), provides client functions. An interactive client program (mclient) is installed with the server. The client does not use multifile's multiplexing capability. That facility is intended for a future hypertext client. To learn how to limit resource consumption, see the entries for the -s, and -n, options in the section titled COMMAND-LINE OPTIONS. ADVERTISEMENT When a client connects to multifile, multifile greets the client with a frame containing a line of UTF-8 text that advertises multifile's version and the maximum number of simultaneous requests multifile is configured to service per connection (the value of the -n option). The values are separated by a colon. The text is zero-terminated. The advertisment has the following form: Multifile-3.28:255 After they read the advertisement, clients send request frames. REQUEST FRAMES Multifile exchanges data with clients in frames of up to 1056 bytes of payload preceded by a 2 byte unsigned payload length header. A client requests up to 255 (or the value of the -n option) resources in a request frame. It is unlikely that you will be able to fit 255 requests in 1056 bytes, but you can piggyback further requests in subsequent request frames as described later in this document. The payload of a request frame consists of fully-qualified Unix file system paths separated by zero bytes and terminated with a zero byte. Text must use the encoding that the server's file system uses. /path/to/file1\0 1561208728/path/to/file2\0 1561208728:4096/path/to/file3\0 1561208728:4096:1024/path/to/file4\0 Components of paths must be separated by virgules (UTF-8 47). Multiple contiguous virgules are not an error in a path. Multiple virgules are collapsed into a single virgule by the kernel and have been since at least UNIX Version 6 of 1975. If the sequence ".." appears as an element in a path, multifile drops the connection. If a path begins with ".", multifile drops the connection. If a path is empty, multifile drops the connection. Paths must begin with a virgule or the UTF-8 represententation of 1 to 3 numbers separated by colons. UNCONDITIONAL REQUESTS A path that begins with a virgule is an unconditional request. If the path describes a file, multifile returns the data in the file in one or more response frames. If the path describes a directory, multifile returns a content listing for the directory. CONDITIONAL REQUESTS A path that begins with numbers is a conditional request. The first number is a time value expressed as the number of seconds since the UNIX epoch (00:00:00 January 1, 1970 UTC). The server only returns data for the requested entity if its modification time is more recent than the time value. The second number is optional. If present, it must be separated from the time value by a colon: ":" (UTF-8 58). The second number is an offset into the file. The server returns data for the file starting from the offset byte. The first byte in a file is numbered 0. This value is ignored with directory requests. The third number is optional. It cannot be present unless the offset is present. If the third number is present, it must be separated from the offset by a colon. The third number is a byte count. The server delivers at most the byte count number of bytes from the file. A request with a byte count of 0 is identical to a request with no count. This value is ignored with directory requests. If a client wants to request a range of bytes unconditionally, the client specifies a time value of 0. If a client wants to request multiple ranges from the same file, the client prefixes each range to a separate request. RESPONSE FRAMES Response data are delivered in multiplexed frames. The first byte of payload of response frames is an unsigned numerical response ID. The value of this number corresponds to the ordinal position of a path in its request frame. The stream of response frames is terminated with a frame with a response ID of 0. In the first response frame for a request, the remaining bytes subsequent to the response ID are the response header. A response header is UTF-8 text describing the number of data bytes to be delivered and the last modification time expressed in seconds since the UNIX epoch. The two values are separated by a colon. The text is zero-terminated. A non- zero count indicates that multifile will deliver data for that request. • If the count is zero and the time is zero, the server could not access the requested entity. Multifile delivers no further response frames for the path. • If the count is zero and the time is non-zero, the conditions of a file or directory request could not be satisfied, or the file is empty. Multifile delivers no further response frames for the path. • If the count is non-zero and the time is non-zero, a file request is successful and the file's data are delivered in subsequent response frames. • If the count is non-zero and the time is zero, the path is a directory path. Multifile successfully opened the directory. The count is inaccurate and should be ignored. The length of the response data is not known in advance. It will be zero if the directory is empty. In response frames subsequent to the first for a request, the remaining bytes subsequent to the response ID are response data. DIRECTORY RESPONSES The payload data returned for directory requests consists of lines of zero-terminated terminated text. The text will be encoded in the encoding used by the server's file system. The payload of the first frame delivered contains the directory's modification time and the directory's name separated by a colon. Each subsequent frame's payload contains the last modification time, size, and name of a directory entry, separated by colons. The name is appended with a virgule if the named entity is a directory. PIGGYBACKED REQUESTS A client can send request frames while it receives response frames. The response IDs for the new requests are the same as they would be if all the active requests had been concatenated into one (potentially oversized) request frame. If a client submits more than 255 total requests (see the -n option), the excess requests are discarded. Note that each request path must fit entirely inside one request frame. Paths cannot be split across frames. If a client submits 255 or fewer total requests and does not receive response frames for piggybacked requests before receving the terminator frame, piggybacking did not occur. The piggybacked requests arrived too late to be piggybacked. Multifile delivers the new requests in a new response stream. STOP FRAMES If a client wants to stop all or part of a response stream, the client sends a stop frame. Then the client continues reading response frames until it reads the terminator frame. Stopped responses cannot be restarted. The payload of a stop frame consists of a series of stop pairs. A stop pair consists of a UTF-8 full-stop character "." (UTF-8 46) followed by the UTF-8 representation of a number. The number must correspond to the ordinal position of a path in its request frame. A stop frame must be zero-terminated. A stop pair with a zero index stops all requests from being delivered. CONNECTION CULLING Multifile closes idle connections every 60 seconds. An idle connection is one that has not generated a response frame for 60 or more seconds. CONFIGURATION By default, FreeBSD limits each process to a low number of maximum simultaneously open descriptors. This places a limit on the number of connections multifile may multiplex. Set these values at the command- line with the "sysctl" utility. Enable them permanently by placing these lines in /etc/sysctl.conf on the host machine. Your system will complain about these values if it lacks resources. kern.maxfiles=262144 kern.maxfilesperproc=131072 Multifile writes its pid into /var/run/multifile.pid. You stop multifile with a SIGTERM. A rc.d script is installed in /usr/local/etc/rc.d/. Add the following lines to /etc/rc.conf to start multifile on system boot. Replace the items in brackets with values appropriate for your system. These are the minimal set of options you should start with. The available options are described in full at the end of this manual page. multifile_enable="YES" multifile_flags="-t -r -u " Start, stop, or restart multifile, or determine if it is running with the following commands. service multifile start service multifile stop service multifile restart service multifile status If you do not want multifile started on system start, set multifile_enable="NO" and use the following commands. service multifile onestart service multifile onestop service multifile onerestart service multifile onestatus COMMAND-LINE OPTIONS The following command line options are recognized. The -t and -r options are mandatory. The rest are optional. -r The -r option specifies the root directory of the server. The server invokes chdir(2) and chroot(2) on the value of this option before changing to the user and group specified by the -u and -g options. -p The -p option specifies the port to listen on. This defaults to 8000. -i By default, multifile accepts connections on all interfaces it can find capable of IPv4 or IPv6. The -i option limits the server to accepting connections from a specified interface. Pass the IP address of the desired interface as argument. -m By default, multifile maintains no more than 1024 simultaneous connections. The -m option changes this value. -n By default, multifile multiplexes up to 255 concurrent responses per connection. To lower this value, pass a positive value to -n. -s The -s option turns off multiplexing. Multifile delivers all response frames for a requested entity before delivering response frames for subsequent requested entities. Multifile queues only one frame for delivery each time the server processes a request queue. Note that this is not the same as setting -n to 1. In that case, the server will only accept 1 request per request frame. With -s present on the command-line and -n set to a value greater than 1, multifile accepts mulitiple requests per request frame, but delivers the response frames for each requested entity serially in requested order. -u -g The -u and the -g options are used to specify the user and group for the server. Both values default to "nobody". -t The -t option specifies the fully qualified path to the TLS configuration file. The file must contain 3 lines of text. The first line is the fully qualified path to the file holding the server key in PEM format. The second line is the password for the key. This line can be blank if there is no password. The third line is the fully qualified path to the file containing the certificate chain in PEM format. AUTHORS James Bailie ⟨jimmy@mammothcheese.ca⟩ http://www.mammothcheese.ca Sat Apr 08, 2023