File-format for Included Files for main.cf Options

[JL (Postfix Readers A/c)]

Hi,

I can't find it in the docs or from a search of this mailing-list...

When a main.cf entry specifies a filename, I know the contents are
inserted in place. But the exact format of said file is unclear.

I don't think it is literally "included" in-line, because a file that
contains a list of domains, one on each line, with no indentation,
seems to work fine for relay_domains, and suchlike.

Can someone point me at the right place in the docs, or offer advice
which maybe could also be added to the docs (!) to help others?

Can such a file contain comments, for example? Or blank lines?
Can it have several "items" space/comma separated on one line?
Can it have each "item" on a line of its own? A mixture of both?

I have tried doing some experiments and I think I have what I need
working as required, but guesswork is not great in a production
environment :)

Thanks,
James.

[Viktor Dukhovni]

On Tue, Jan 12, 2021 at 01:00:26AM +0000, JL (Postfix Readers A/c) wrote:

> Can someone point me at the right place in the docs, or offer advice
> which maybe could also be added to the docs (!) to help others?

Each main.cf parameter documents its syntax.  Various parameters, that
take literal lists of values in-line, also take a file name whose
content contains similar values.  The syntax typically also supports
"!/some/path", which is a set of exceptions.

> Can such a file contain comments, for example? Or blank lines?
> Can it have several "items" space/comma separated on one line?
> Can it have each "item" on a line of its own? A mixture of both?

    http://www.postfix.org/postconf.5.html#relay_domains

    Specify a list of host or domain names, "/file/name" patterns or
    "type:table" lookup tables, separated by commas and/or whitespace.
    Continue long lines by starting the next line with whitespace. A
    "/file/name" pattern is replaced by its contents; a "type:table"
    lookup table is matched when a (parent) domain appears as lookup
    key. Specify "!pattern" to exclude a domain from the list. The form
    "!/file/name" is supported only in Postfix version 2.4 and later.

The file content is interpolated into the value of the parameter,
as though each line were an indented continuation of the parameter
value:

        relay_domains = /some/file

is the same as:

        relay_domains =
            line1
            line2
            ...
            lineN

where line1, line2, ... lineN are the lines of the file.  Comments must
start in the first column of the file.  Blank lines are ignored, just
as they are in the in-line form.  Files can even list more files, and
each '!' reverses the meaning of any previous '!'.

These are called "match lists" internally, and it would perhaps be good
to have a general description of match lists somewhere...

--
    Viktor.

[JL (Postfix Readers A/c)]

Hi,

Thank you Viktor, that is absolutely perfect!

In particular, your explanation -- "The file content is interpolated
into the value of the parameter, as though each line were an indented
continuation of the parameter..." -- clarifies exactly what I needed
to know.

I am sure it's not in the documentation anywhere. It's not clear where
would be a good place to write it up, without repeating the
explanation in-line everywhere a file argument is mentioned.

The additional clarification about comments needing to start in the
first column was helpful, and good to know about the additional points
regarding !negation and files including files etc.

Thanks again!

James.



On Tue, 12 Jan 2021 at 01:22, Viktor Dukhovni <[hidden email]> wrote:

>
> On Tue, Jan 12, 2021 at 01:00:26AM +0000, JL (Postfix Readers A/c) wrote:
>
> > Can someone point me at the right place in the docs, or offer advice
> > which maybe could also be added to the docs (!) to help others?
>
> Each main.cf parameter documents its syntax.  Various parameters, that
> take literal lists of values in-line, also take a file name whose
> content contains similar values.  The syntax typically also supports
> "!/some/path", which is a set of exceptions.
>
> > Can such a file contain comments, for example? Or blank lines?
> > Can it have several "items" space/comma separated on one line?
> > Can it have each "item" on a line of its own? A mixture of both?
>
>     http://www.postfix.org/postconf.5.html#relay_domains
>
>     Specify a list of host or domain names, "/file/name" patterns or
>     "type:table" lookup tables, separated by commas and/or whitespace.
>     Continue long lines by starting the next line with whitespace. A
>     "/file/name" pattern is replaced by its contents; a "type:table"
>     lookup table is matched when a (parent) domain appears as lookup
>     key. Specify "!pattern" to exclude a domain from the list. The form
>     "!/file/name" is supported only in Postfix version 2.4 and later.
>
> The file content is interpolated into the value of the parameter,
> as though each line were an indented continuation of the parameter
> value:
>
>         relay_domains = /some/file
>
> is the same as:
>
>         relay_domains =
>             line1
>             line2
>             ...
>             lineN
>
> where line1, line2, ... lineN are the lines of the file.  Comments must
> start in the first column of the file.  Blank lines are ignored, just
> as they are in the in-line form.  Files can even list more files, and
> each '!' reverses the meaning of any previous '!'.
>
> These are called "match lists" internally, and it would perhaps be good
> to have a general description of match lists somewhere...
>
> --
>     Viktor.