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.

[Dominic Raferd]

On 12/01/2021 01:21, Viktor Dukhovni 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...

How to know which parameters accept a filename as argument in this way?

By experiment, myorigin does but mydomain and myhostname do not. It
would be helpful (to me) if myhostname took a filename as argument.

[Wietse Venema]

Dominic Raferd:
[ Charset ISO-8859-15 converted... ]

> On 12/01/2021 01:21, Viktor Dukhovni 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...
>
> How to know which parameters accept a filename as argument in this way?
>
> By experiment, myorigin does but mydomain and myhostname do not. It
> would be helpful (to me) if myhostname took a filename as argument.

htp://www.postfix.org/postconf.5.html sats:

myhostname (default: see postconf -d output)
    The internet hostname of this mail system. The default is to
    use the fully-qualified domain name (FQDN) from gethostname(),
    or to use the non-FQDN result from gethostname() and append
    ".$mydomain". $myhostname is used as a default value for many
    other configuration parameters.

   Example:

   myhostname = host.example.com

That was not so difficult.

        Wietse

[Viktor Dukhovni]

On Fri, Feb 12, 2021 at 11:14:24AM +0000, Dominic Raferd wrote:

> On 12/01/2021 01:21, Viktor Dukhovni 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...
>
> How to know which parameters accept a filename as argument in this way?
>
> By experiment, myorigin does but mydomain and myhostname do not. It
> would be helpful (to me) if myhostname took a filename as argument.

You're perhaps confusing myorigin with mydestination.

The myorigin parameter is also not a match list, and so (in the
"upstream" official Postfix releases) does not support indirect
specification via a file.

I am not aware of any "single-valued" parameters that are match lists in
the upstream release.  Debian patches Postfix to support an external
file for (IIRC) myhostname, but that's not something that you'll see
otherwise.

--
    Viktor.

[Chris Green-11]

On Fri, Feb 12, 2021 at 01:08:07PM -0500, Viktor Dukhovni wrote:

> On Fri, Feb 12, 2021 at 11:14:24AM +0000, Dominic Raferd wrote:
>
> > On 12/01/2021 01:21, Viktor Dukhovni 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...
> >
> > How to know which parameters accept a filename as argument in this way?
> >
> > By experiment, myorigin does but mydomain and myhostname do not. It
> > would be helpful (to me) if myhostname took a filename as argument.
>
> You're perhaps confusing myorigin with mydestination.
>
> The myorigin parameter is also not a match list, and so (in the
> "upstream" official Postfix releases) does not support indirect
> specification via a file.
>
> I am not aware of any "single-valued" parameters that are match lists in
> the upstream release.  Debian patches Postfix to support an external
> file for (IIRC) myhostname, but that's not something that you'll see
> otherwise.
>

The Debian patch sets myorigin:-

    # Debian GNU/Linux specific:  Specifying a file name will cause the
    # first line of that file to be used as the name.  The Debian default
    # is /etc/mailname.
    #
    #myorigin = /etc/mailname


--
Chris Green

[Viktor Dukhovni]

On Fri, Feb 12, 2021 at 06:35:50PM +0000, Chris Green wrote:

> The Debian patch sets myorigin:-
>
>     # Debian GNU/Linux specific:  Specifying a file name will cause the
>     # first line of that file to be used as the name.  The Debian default
>     # is /etc/mailname.
>     #
>     #myorigin = /etc/mailname

Noted.  But this is still not a match-list, just a parameter-specific,
value-only "include-lite" hack.  Thus semantically distinct from, e.g.,
"mydestination", "relay_domains", "virtual_alias_domains",
"virtual_mailbox_domains", and various other match-lists.

--
    Viktor.

[Dominic Raferd]

On 12/02/2021 18:35, Chris Green wrote:

> On Fri, Feb 12, 2021 at 01:08:07PM -0500, Viktor Dukhovni wrote:
>> On Fri, Feb 12, 2021 at 11:14:24AM +0000, Dominic Raferd wrote:
>>
>>> On 12/01/2021 01:21, Viktor Dukhovni 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...
>>> How to know which parameters accept a filename as argument in this way?
>>>
>>> By experiment, myorigin does but mydomain and myhostname do not. It
>>> would be helpful (to me) if myhostname took a filename as argument.
>> You're perhaps confusing myorigin with mydestination.
>>
>> The myorigin parameter is also not a match list, and so (in the
>> "upstream" official Postfix releases) does not support indirect
>> specification via a file.
>>
>> I am not aware of any "single-valued" parameters that are match lists in
>> the upstream release.  Debian patches Postfix to support an external
>> file for (IIRC) myhostname, but that's not something that you'll see
>> otherwise.
>>
> The Debian patch sets myorigin:-
>
>      # Debian GNU/Linux specific:  Specifying a file name will cause the
>      # first line of that file to be used as the name.  The Debian default
>      # is /etc/mailname.
>      #
>      #myorigin = /etc/mailname

Thanks yes this is what I had in mind - I run postfix on Debian-derived
distro (Ubuntu) and I had not realised that Debian patched the postfix
source code; this explains why it is not mentioned in the postfix docs.