2022-03-11 20:45:06

by Thiago Becker

[permalink] [raw]
Subject: [RFC v2 PATCH 7/7] readahead: documentation

Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1946283
Signed-off-by: Thiago Becker <[email protected]>
---
tools/nfs-readahead-udev/Makefile.am | 2 +
.../nfs-readahead-udev/nfs-readahead-udev.man | 47 +++++++++++++++++++
tools/nfs-readahead-udev/readahead.conf | 14 ++++++
3 files changed, 63 insertions(+)
create mode 100644 tools/nfs-readahead-udev/nfs-readahead-udev.man

diff --git a/tools/nfs-readahead-udev/Makefile.am b/tools/nfs-readahead-udev/Makefile.am
index 010350aa..eaa9b90e 100644
--- a/tools/nfs-readahead-udev/Makefile.am
+++ b/tools/nfs-readahead-udev/Makefile.am
@@ -10,6 +10,8 @@ udev_rules_DATA = 99-nfs_bdi.rules
ra_confdir = $(sysconfdir)
ra_conf_DATA = readahead.conf

+man5_MANS = nfs-readahead-udev.man
+
99-nfs_bdi.rules: 99-nfs_bdi.rules.in $(builddefs)
$(SED) "s|_libexecdir_|@libexecdir@|g" 99-nfs_bdi.rules.in > $@

diff --git a/tools/nfs-readahead-udev/nfs-readahead-udev.man b/tools/nfs-readahead-udev/nfs-readahead-udev.man
new file mode 100644
index 00000000..2477d5b3
--- /dev/null
+++ b/tools/nfs-readahead-udev/nfs-readahead-udev.man
@@ -0,0 +1,47 @@
+.\" Manpage for nfs-readahead-udev.
+.nh
+.ad l
+.TH man 5 "08 Mar 2022" "1.0" "nfs-readahead-udev man page"
+.SH NAME
+
+nfs-readahead-udev \- Find the readahead for a given NFS mount
+
+.SH SYNOPSIS
+
+nfs-readahead-udev <device>
+
+.SH DESCRIPTION
+
+\fInfs-readahead-udev\fR is a tool intended to be used with udev to set the \fIread_ahead_kb\fR parameter of NFS mounts, according to the configuration file (see \fICONFIGURATION\fR). \fIdevice\fR is the device number for the NFS backing device as provided by the kernel.
+
+.SH CONFIGURATION
+
+The configuration file (\fI/etc/readahead.conf\fR) contains the readahead configuration, and is formatted as follows.
+
+<LINES> ::= <LINES> <LINE> | <LINE>
+
+<LINE> ::= <TOKENS> <ENDL>
+
+<TOKENS> ::= <TOKENS> <TOKEN> | <TOKEN>
+
+<TOKEN> ::= default | <PAIR>
+
+<PAIR> ::= mountpoint = <mountpoint> | fstype = <nfs|nfs4> | readahead = <readahead>
+
+\fImountpoint\fR is the path in the system where the file system is mounted.
+
+\fIreadahead\fR is an integer to readahead.
+
+\fIfstype\fR is either \fInfs\fR or \fInfs4\fR.
+
+.SH SEE ALSO
+
+mount.nfs(8), nfs(5), udev(7), bcc-readahead(8)
+
+.SH BUGS
+
+No known bugs.
+
+.SH AUTHOR
+
+Thiago Rafael Becker <[email protected]>
diff --git a/tools/nfs-readahead-udev/readahead.conf b/tools/nfs-readahead-udev/readahead.conf
index 988b30c7..bce830f1 100644
--- a/tools/nfs-readahead-udev/readahead.conf
+++ b/tools/nfs-readahead-udev/readahead.conf
@@ -1 +1,15 @@
+# nfs-readahead-udev configuration file.
+#
+# This file configures the readahead for nfs mounts when those are anounced by the kernel.
+# The file is composed on lines that can contain either the default configuration (applied to
+# any nfs mount that does not match any of the other lines) or a combination of
+# mountpoint=<mountpoint> where mountpoint is the mount point for the file system
+# fstype=<nfs|nfs4> specifies that this configuration should only apply to a specific nfs
+# version.
+# Every line must contain a readahead option, with the expected readahead value.
default readahead=128
+
+# mountpoint=/mnt readahead=4194304
+# fstype=nfs readahead=4194304
+# fstype=nfs4 readahead=4194304
+# mountpoint=/mnt fstype=nfs4 readahead=4194304
--
2.35.1


2022-03-17 19:47:41

by Steve Dickson

[permalink] [raw]
Subject: Re: [RFC v2 PATCH 7/7] readahead: documentation



On 3/11/22 2:06 PM, Thiago Becker wrote:
> Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1946283
> Signed-off-by: Thiago Becker <[email protected]>
> ---
> tools/nfs-readahead-udev/Makefile.am | 2 +
> .../nfs-readahead-udev/nfs-readahead-udev.man | 47 +++++++++++++++++++
> tools/nfs-readahead-udev/readahead.conf | 14 ++++++
> 3 files changed, 63 insertions(+)
> create mode 100644 tools/nfs-readahead-udev/nfs-readahead-udev.man
>
> diff --git a/tools/nfs-readahead-udev/Makefile.am b/tools/nfs-readahead-udev/Makefile.am
> index 010350aa..eaa9b90e 100644
> --- a/tools/nfs-readahead-udev/Makefile.am
> +++ b/tools/nfs-readahead-udev/Makefile.am
> @@ -10,6 +10,8 @@ udev_rules_DATA = 99-nfs_bdi.rules
> ra_confdir = $(sysconfdir)
> ra_conf_DATA = readahead.conf
>
> +man5_MANS = nfs-readahead-udev.man
> +
> 99-nfs_bdi.rules: 99-nfs_bdi.rules.in $(builddefs)
> $(SED) "s|_libexecdir_|@libexecdir@|g" 99-nfs_bdi.rules.in > $@
>
> diff --git a/tools/nfs-readahead-udev/nfs-readahead-udev.man b/tools/nfs-readahead-udev/nfs-readahead-udev.man
> new file mode 100644
> index 00000000..2477d5b3
> --- /dev/null
> +++ b/tools/nfs-readahead-udev/nfs-readahead-udev.man
> @@ -0,0 +1,47 @@
> +.\" Manpage for nfs-readahead-udev.
> +.nh
> +.ad l
> +.TH man 5 "08 Mar 2022" "1.0" "nfs-readahead-udev man page"
> +.SH NAME
> +
> +nfs-readahead-udev \- Find the readahead for a given NFS mount
> +
> +.SH SYNOPSIS
> +
> +nfs-readahead-udev <device>
> +
> +.SH DESCRIPTION
> +
> +\fInfs-readahead-udev\fR is a tool intended to be used with udev to set the \fIread_ahead_kb\fR parameter of NFS mounts, according to the configuration file (see \fICONFIGURATION\fR). \fIdevice\fR is the device number for the NFS backing device as provided by the kernel.
> +
> +.SH CONFIGURATION
> +
> +The configuration file (\fI/etc/readahead.conf\fR) contains the readahead configuration, and is formatted as follows.
> +
> +<LINES> ::= <LINES> <LINE> | <LINE>
> +
> +<LINE> ::= <TOKENS> <ENDL>
> +
> +<TOKENS> ::= <TOKENS> <TOKEN> | <TOKEN>
> +
> +<TOKEN> ::= default | <PAIR>
> +
> +<PAIR> ::= mountpoint = <mountpoint> | fstype = <nfs|nfs4> | readahead = <readahead>
> +
> +\fImountpoint\fR is the path in the system where the file system is mounted.
> +
> +\fIreadahead\fR is an integer to readahead.
> +
> +\fIfstype\fR is either \fInfs\fR or \fInfs4\fR.
> +
> +.SH SEE ALSO
> +
> +mount.nfs(8), nfs(5), udev(7), bcc-readahead(8)
> +
> +.SH BUGS
> +
> +No known bugs.
> +
> +.SH AUTHOR
I think it might make sense to added some examples
on how the command will be used.

> +
> +Thiago Rafael Becker <[email protected]>
> diff --git a/tools/nfs-readahead-udev/readahead.conf b/tools/nfs-readahead-udev/readahead.conf
> index 988b30c7..bce830f1 100644
> --- a/tools/nfs-readahead-udev/readahead.conf
> +++ b/tools/nfs-readahead-udev/readahead.conf
> @@ -1 +1,15 @@
> +# nfs-readahead-udev configuration file.
> +#
> +# This file configures the readahead for nfs mounts when those are anounced by the kernel.
> +# The file is composed on lines that can contain either the default configuration (applied to
> +# any nfs mount that does not match any of the other lines) or a combination of
> +# mountpoint=<mountpoint> where mountpoint is the mount point for the file system
> +# fstype=<nfs|nfs4> specifies that this configuration should only apply to a specific nfs
> +# version.
> +# Every line must contain a readahead option, with the expected readahead value.
> default readahead=128
> +
> +# mountpoint=/mnt readahead=4194304
> +# fstype=nfs readahead=4194304
> +# fstype=nfs4 readahead=4194304
> +# mountpoint=/mnt fstype=nfs4 readahead=4194304
Would it make sense to try added these to nfs.conf?

I must admin I'm a bit impressed with your lex and
yacc routines in patch 5, I have not seen those
in a while.. but that does add more dependencies
to nfs-utils and as well as yet another config file
to manage.

steved.

2022-03-18 18:49:53

by Thiago Becker

[permalink] [raw]
Subject: Re: [RFC v2 PATCH 7/7] readahead: documentation

Thanks for the comments.


On Thu, Mar 17, 2022 at 12:37 PM Steve Dickson <[email protected]> wrote:
> I think it might make sense to added some examples
> on how the command will be used.

Will do.

> Would it make sense to try added these to nfs.conf?
>
> I must admin I'm a bit impressed with your lex and
> yacc routines in patch 5, I have not seen those
> in a while.. but that does add more dependencies
> to nfs-utils and as well as yet another config file
> to manage.

I debated with a funko pop between writing the parser and using a parser
builder. Originally, the idea was to provide more possibilities, like
configuring the read ahead of other devices, but those BDIs don't
announce themselves when they are added like NFS does. I also don't know
how useful it would be. So this idea is scrapped for now.

Here are the debate conclusions:
- writing the parser would add some complexity that lex/yacc handles
- lex/yacc add build time dependencies and some bloat
- error handling is painful with lex/yacc
- lex/yacc are well known
- using a parser combinator would be my preference, but I couldn't
find any written in c that didn't add a new library to the systems

It seemed to me that using lex/yacc was the best choice taking into
account the needs of both limited storage systems and large servers.

I can still see some configurations that may be added in the future,
like setting the read ahead per server, network segment, but I believe
that the configurations we have cover most of the use cases.

I've added a new configuration because I planned to have a more fine
grained configuration for multiple file systems/designs, and that
would add a lot in nfs.conf (and tie the tool to nfs).

And, to be completely honest, I took what I've done in
https://github.com/trbecker/readahead-utils
and ported it to nfs-utils.

That's the history so far. I don't mind taking stuff out if it would
make the software more maintainable.


> steved.
>

thiago