svn commit: r297690 - head/sys/boot/forth

[Maxim Sobolev]

Hi Bruce, thanks for the input! I will see if I can move that piece into
loader.8 and extend it a bit from the source "documentation".

-Max

On Thu, Apr 7, 2016 at 8:38 PM, Bruce Evans <brde at optusnet.com.au> wrote:

> On Fri, 8 Apr 2016, Maxim Sobolev wrote:
>
> Log:
>>  Document vfs.root.mountfrom.
>>
>>  Reviewed by:   imp, wblock
>>
>
> The format of this variable is still undocumented, except in the source
> code.
>
> Modified: head/sys/boot/forth/loader.conf.5
>>
>> ==============================================================================
>> --- head/sys/boot/forth/loader.conf.5   Fri Apr  8 00:01:19 2016
>> (r297689)
>> +++ head/sys/boot/forth/loader.conf.5   Fri Apr  8 00:24:21 2016
>> (r297690)
>>
>
> This variable is (partly) documented in a different wrong file than the
> source file.  It isn't a loader option.  It is a kernel tunable.  No
> other kernel tunables are documented in loader.conf.5.  Some of them are
> documented in loader.8 (not really the right place --- loader is just 1
> way of setting them, and isn't a way of reading or interpreting them).
> loader.8 also documents most loader options as BUILTIN ENVIRONMENT
> VARIABLES.  It does this much better than loader.conf.5.  It documents
> 30 such options and only has a couple of ordering errors in the list,
> whie loader.conf.5 documents 15 such options in random order.  About
> half of the 15 are in both, and their descriptions give quite different
> details in a quite different style (too much double quoting in
> loader.conf.5).  loader.8 documents only 16 tunables, with more ordering
> errors that for options.
>
> @@ -112,6 +112,31 @@ The name must be a subdirectory of
>> that contains a kernel.
>> .It Ar kernel_options
>> Flags to be passed to the kernel.
>> +.It Ar vfs.root.mountfrom
>> +Specify the root partition to mount.
>> +For example:
>> +.Pp
>> +.Dl vfs.root.mountfrom="ufs:/dev/da0s1a"
>>
>
> The source code gives the details needed to actually use this variable
> without guessing from a single example.  It gives both an informal and
> formal description:
>
> X /*
> X  * The root filesystem is detailed in the kernel environment variable
> X  * vfs.root.mountfrom, which is expected to be in the general format
> X  *
> X  * <vfsname>:[<path>][  <vfsname>:[<path>] ...]
> X  * vfsname   := the name of a VFS known to the kernel and capable
> X  *              of being mounted as root
> X  * path      := disk device name or other data used by the filesystem
> X  *              to locate its physical store
> X  *
> X  * If the environment variable vfs.root.mountfrom is a space separated
> list,
> X  * each list element is tried in turn and the root filesystem will be
> mounted
> X  * from the first one that suceeds.
> X  *
> X  * The environment variable vfs.root.mountfrom.options is a comma
> delimited
> X  * set of string mount options.  These mount options must be parseable
> X  * by nmount() in the kernel.
> X  */
>
> I thought that these careful descriptions were broken using sbufs which
> accidentally (?) changed the separator from space to newline.  However,
> I can' find any trace of this in my config files -- they now just use
> a space.  I might have just been confused by old kernels not supporting
> lists.
>
> I mainly use this feaature to work around the renaming of ad to ada and
> loss of the compatibility support for this.  My lists look like
> "ufs:ad4s3a ufs:ada0s3a ufs:ad0s2a".  Old kernels don't support lists,
> but they also don't support ada; they use the first entry and this works
> although the documentation says it shouldn't (the comment says that
> the format is <vfsname>:[<path>] and doesn't mention field separators or
> trailing garbage).  FreeBSD-11 doesn't supprt ad, but it supports lists;
> so it uses the second entry.  This works on 2 systems with similar disk
> numbering.  The third entry is for another system with different disk
> numbering an no ad4.  This almost never works -- with old kernels, the
> list doesn't work, and with new kernels the list works and ada0 exists
> and ada0s3a exists, but it is not the right boot partition.  This works
> with intermediate kernels with lists but no ada0, so that the third
> entry is used.
>
> Bruce
>
>