</listitem>
</varlistentry>
<varlistentry>
- <term><option>user</option></term>
- <listitem>
- <para>
- Optional; string.
- </para>
+ <term><option>listenaddr</option></term>
+ <listitem>
<para>
- The name of the user this server must run as. If this
- parameter is not specified, then nbd-server will not
- attempt to change its UID (so the UID it runs as will be
- the user who starts nbd-server). If it is specified, then
- nbd-server will change its UID after opening ports, but
- before accepting connections or opening files.
+ Optional; string
</para>
- </listitem>
+ <para>If this option is set, it should contain the local IP
+ address on which we should listen to
+ <command>nbd-client</command>(8) connections. If it is not
+ set, <command>nbd-server</command> will listen to all
+ local IPv4 and IPv6 addresses. To limit to IPv6, specify the
+ address as "::". To limit to IPv4, specify as "0.0.0.0". It
+ is not possible to specify more than one IP address
+ here.</para>
+ </listitem>
</varlistentry>
<varlistentry>
<term><option>oldstyle</option></term>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>listenaddr</option></term>
+ <term><option>port</option></term>
<listitem>
<para>
Optional; string
</para>
- <para>If this option is set, it should contain the local IP
- address on which we should listen to
- <command>nbd-client</command>(8) connections. If it is not
- set, <command>nbd-server</command> will listen to all
- local IPv4 and IPv6 addresses. To limit to IPv6, specify the
- address as "::". To limit to IPv4, specify as "0.0.0.0". It
- is not possible to specify more than one IP address
- here.</para>
+ <para>
+ The port on which to listen for new-style nbd-client
+ connections. If not specified, the IANA-assigned port of
+ 10809 is used.
+ </para>
</listitem>
- </varlistentry
+ </varlistentry>
+ <varlistentry>
+ <term><option>user</option></term>
+ <listitem>
+ <para>
+ Optional; string.
+ </para>
+ <para>
+ The name of the user this server must run as. If this
+ parameter is not specified, then nbd-server will not
+ attempt to change its UID (so the UID it runs as will be
+ the user who starts nbd-server). If it is specified, then
+ nbd-server will change its UID after opening ports, but
+ before accepting connections or opening files.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
<refsect1>
</listitem>
</varlistentry>
<varlistentry>
+ <term><option>flush</option></term>
+ <listitem>
+ <para>Optional; boolean.</para>
+ <para>When this option is enabled,
+ <command>nbd-server</command> will inform the client that it
+ supports and desires to be sent flush requests when the
+ elevator layer receives them. Receipt of a flush request
+ will cause an fdatasync() (or, if the sync option is set,
+ an fsync()) on the backend storage. This increases
+ reliability in the case of an unclean shutdown at
+ the expense of a degradation of performance. This option
+ will have no effect unless supported by the client.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>fua</option></term>
+ <listitem>
+ <para>Optional; boolean.</para>
+ <para>When this option is enabled,
+ <command>nbd-server</command> will inform the client that it
+ supports and desires to be sent fua (force unit access) commands
+ when the elevator layer receives them. Receipt of a force unit
+ access command will cause the specified command to be synced
+ to backend storage using sync_file_range() if supported, or
+ fdatasync() otherwise. This increases
+ reliability in the case of an unclean shutdown at
+ the expense of a degradation of performance. This option
+ will have no effect unless supported by the client.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term>listenaddr</term>
<listitem>
<para>
</listitem>
</varlistentry>
<varlistentry>
+ <term><option>maxconnections</option></term>
+ <listitem>
+ <para>Optional; integer</para>
+ <para>
+ If specified, then it limits the number of opened connections for
+ this export.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><option>multifile</option></term>
<listitem>
<para>Optional; boolean.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>readonly</option></term>
+ <term><option>postrun</option></term>
<listitem>
- <para>Optional; boolean.</para>
+ <para>Optional; string</para>
<para>
- Disallow writes to the device. If this option is
- specified, <command>nbd-server</command> will issue an
- error to any client that tries to write to the device.
+ If specified, then it is assumed to be a command
+ that will be ran when a client has
+ disconnected. This can be useful to clean up
+ whatever <option>prerun</option> has set up, to log
+ something, or similar.
</para>
<para>
- Use of this option in conjunction with
- <option>copyonwrite</option> is possible, but silly.
+ If the literal string '%s' is present in the
+ command, it will be replaced by the file name that
+ has just been closed.
+ </para>
+ <para>
+ In contrast to the <option>prerun</option> option,
+ the exit state of <option>postrun</option> is
+ <emphasis>ignored</emphasis>.
</para>
- <para>Corresponds to the <option>-r</option> option on the
- command line.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>sdp</option></term>
+ <term><option>prerun</option></term>
<listitem>
- <para>Optional; boolean.</para>
+ <para>Optional; string</para>
<para>
- When this option is enabled, <command>nbd-server</command>
- will use the Socket Direct Protocol (SDP) to serve the
- export, rather than just IP. This is faster, but requires
- special hardware (usually something like InfiniBand) and
- support in the kernel.
+ If specified, then this command will be ran after a
+ client has connected to the server (and has been
+ accepted), but before the server starts serving. If
+ the command contains the literal string '%s', then
+ this string will be replaced by the filename of the
+ file which nbd-server wants to export.
</para>
<para>
- Additionally, support for this option must be enabled at
- compile time, using the <option>--enable-sdp</option> option
- to the <command>configure</command> script. If this option
- is found in a configuration file and
- <command>nbd-server</command> does not have support for SDP,
- then <command>nbd-server</command> will exit with an error
- message.
+ This is useful to create export files on the fly, or
+ to verify that a file can be used for export, to
+ write something to a log file, or similar.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>sync</option></term>
- <listitem>
- <para>Optional; boolean.</para>
- <para>When this option is enabled,
- <command>nbd-server</command> will call an fsync() after every
- write to the backend storage. Calling fsync() increases
- reliability in case of an unclean shutdown of nbd-server; but,
- depending on the file system used on the nbd-server side, may
- degrade performance. The use of this option isn't always
- necessary; e.g., on ext3 filesystems, it is recommended that
- it is <emphasis>not</emphasis> enabled, since it seriously
- reduces performance on ext3 filesystems while not
- importantly impacting reliability.
+ <para>
+ If the command runs with a non-zero exit status,
+ then nbd-server will assume the export will fail,
+ and refuse to serve it.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>flush</option></term>
+ <term><option>readonly</option></term>
<listitem>
<para>Optional; boolean.</para>
- <para>When this option is enabled,
- <command>nbd-server</command> will inform the client that it
- supports and desires to be sent flush requests when the
- elevator layer receives them. Receipt of a flush request
- will cause an fdatasync() (or, if the sync option is set,
- an fsync()) on the backend storage. This increases
- reliability in the case of an unclean shutdown at
- the expense of a degradation of performance. The default
- state is disabled. This option will have no effect unless
- supported by the client.
+ <para>
+ Disallow writes to the device. If this option is
+ specified, <command>nbd-server</command> will issue an
+ error to any client that tries to write to the device.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>fua</option></term>
- <listitem>
- <para>Optional; boolean.</para>
- <para>When this option is enabled,
- <command>nbd-server</command> will inform the client that it
- supports and desires to be sent fua (force unit access) commands
- when the elevator layer receives them. Receipt of a force unit
- access command will cause the specified command to be synced
- to backend storage using sync_file_range() if supported, or
- fdatasync() otherwise. This increases
- reliability in the case of an unclean shutdown at
- the expense of a degradation of performance. The default
- state is disabled. This option will have no effect unless
- supported by the client.
+ <para>
+ Use of this option in conjunction with
+ <option>copyonwrite</option> is possible, but silly.
</para>
+ <para>Corresponds to the <option>-r</option> option on the
+ command line.</para>
</listitem>
</varlistentry>
<varlistentry>
<listitem>
<para>Optional; boolean.</para>
<para>When this option is enabled,
- <command>nbd-server</command> will inform the client that it
- it would prefer it to send requests in elevator order, perhaps
+ <command>nbd-server</command> will inform the client that
+ it would prefer it to send requests in elevator (i.e., optimized) order, perhaps
because it has a backing store and no local elevator. By
default, the client uses QUEUE_FLAG_NONROT, which effectively
restricts the function of the elevator to block merges. By
</listitem>
</varlistentry>
<varlistentry>
+ <term><option>sdp</option></term>
+ <listitem>
+ <para>Optional; boolean.</para>
+ <para>
+ When this option is enabled, <command>nbd-server</command>
+ will use the Socket Direct Protocol (SDP) to serve the
+ export, rather than just IP. This is faster, but requires
+ special hardware (usually something like InfiniBand) and
+ support in the kernel.
+ </para>
+ <para>
+ Additionally, support for this option must be enabled at
+ compile time, using the <option>--enable-sdp</option> option
+ to the <command>configure</command> script. If this option
+ is found in a configuration file and
+ <command>nbd-server</command> does not have support for SDP,
+ then <command>nbd-server</command> will exit with an error
+ message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><option>sparse_cow</option></term>
<listitem>
<para>Optional; boolean.</para>
</listitem>
</varlistentry>
<varlistentry>
+ <term><option>sync</option></term>
+ <listitem>
+ <para>Optional; boolean.</para>
+ <para>When this option is enabled,
+ <command>nbd-server</command> will call an fsync() after every
+ write to the backend storage. Calling fsync() increases
+ reliability in case of an unclean shutdown of nbd-server; but,
+ depending on the file system used on the nbd-server side, may
+ degrade performance. The use of this option isn't always
+ necessary; e.g., on ext3 filesystems, it is recommended that
+ it is <emphasis>not</emphasis> enabled, since it seriously
+ reduces performance on ext3 filesystems while not
+ importantly impacting reliability.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><option>timeout</option></term>
<listitem>
<para>Optional; integer; default 0</para>
</listitem>
</varlistentry>
<varlistentry>
+ <term><option>transactionlog</option></term>
+ <listitem>
+ <para>Optional; string</para>
+ <para>
+ If specified, then this pathname is used to generate a transaction
+ log. A transaction log is a binary file consisting of the requests
+ sent to and the replies received by the server, but excluding any
+ data (so, for a write command, it records the offset and length
+ of the write but not the data written). It is therefore relatively
+ safe to distribute to a third party. Note that the transaction log
+ does not include the negotiation sequence. Transaction logs are
+ mainly useful for debugging. The program
+ <emphasis>nbd-tester-client</emphasis> distributed with the source
+ to this program can reply a transaction log against a server and
+ perform a data integrity test. Note that the transaction log is
+ written to for every client opened. If it is necessary to maintain
+ separate transaction logs for each client, the
+ <emphasis>prerun</emphasis> script should rename the transaction log
+ (which will just have been opened in order to avoid transaction logs
+ overwriting eachother. This action should be race-free.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><option>virtstyle</option></term>
<listitem>
<para>Optional; string; default "ipliteral"</para>
</variablelist>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>prerun</option></term>
- <listitem>
- <para>Optional; string</para>
- <para>
- If specified, then this command will be ran after a
- client has connected to the server (and has been
- accepted), but before the server starts serving. If
- the command contains the literal string '%s', then
- this string will be replaced by the filename of the
- file which nbd-server wants to export.
- </para>
- <para>
- This is useful to create export files on the fly, or
- to verify that a file can be used for export, to
- write something to a log file, or similar.
- </para>
- <para>
- If the command runs with a non-zero exit status,
- then nbd-server will assume the export will fail,
- and refuse to serve it.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>postrun</option></term>
- <listitem>
- <para>Optional; string</para>
- <para>
- If specified, then it is assumed to be a command
- that will be ran when a client has
- disconnected. This can be useful to clean up
- whatever <option>prerun</option> has set up, to log
- something, or similar.
- </para>
- <para>
- If the literal string '%s' is present in the
- command, it will be replaced by the file name that
- has just been closed.
- </para>
- <para>
- In contrast to the <option>prerun</option> option,
- the exit state of <option>postrun</option> is
- <emphasis>ignored</emphasis>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>maxconnections</option></term>
- <listitem>
- <para>Optional; integer</para>
- <para>
- If specified, then it limits the number of opened connections for
- this export.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>transactionlog</option></term>
- <listitem>
- <para>Optional; string</para>
- <para>
- If specified, then this pathname is used to generate a transaction
- log. A transaction log is a binary file consisting of the requests
- sent to and the replies received by the server, but excluding any
- data (so, for a write command, it records the offset and length
- of the write but not the data written). It is therefore relatively
- safe to distribute to a third party. Note that the transaction log
- does not include the negotiation sequence. Transaction logs are
- mainly useful for debugging. The program
- <emphasis>nbd-tester-client</emphasis> distributed with the source
- to this program can reply a transaction log against a server and
- perform a data integrity test. Note that the transaction log is
- written to for every client opened. If it is necessary to maintain
- separate transaction logs for each client, the
- <emphasis>prerun</emphasis> script should rename the transaction log
- (which will just have been opened in order to avoid transaction logs
- overwriting eachother. This action should be race-free.
- </para>
- </listitem>
- </varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
- <para>nbd-server (1), nbd-client (8)</para>
+ <para>nbd-server (1), nbd-client (8), nbd-trdump (8)</para>
</refsect1>
projects / nbd.git / blobdiff