Discussion:
documentation and required version
(too old to reply)
Reindl Harald
2014-07-30 11:21:14 UTC
Permalink
http://www.freedesktop.org/software/systemd/man/systemd.exec.html

such error messages caused by list all sort of options
without any information when they where introduced are
really annoying - the docs should clearly say the minimum
required systemd version and the more options are added
the more important is that

Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:10] Unknown lvalue 'RuntimeDirectory' in
section 'Service'
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:11] Unknown lvalue 'RuntimeDirectoryMode' in
section 'Service
Tom Gundersen
2014-07-30 11:58:51 UTC
Permalink
Post by Reindl Harald
http://www.freedesktop.org/software/systemd/man/systemd.exec.html
such error messages caused by list all sort of options
without any information when they where introduced are
really annoying - the docs should clearly say the minimum
required systemd version and the more options are added
the more important is that
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:10] Unknown lvalue 'RuntimeDirectory' in
section 'Service'
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:11] Unknown lvalue 'RuntimeDirectoryMode' in
section 'Service
Won't this be solved by using the man pages shipped with the version
of systemd you are using?

Cheers,

Tom
Reindl Harald
2014-07-30 12:08:08 UTC
Permalink
Post by Tom Gundersen
Post by Reindl Harald
http://www.freedesktop.org/software/systemd/man/systemd.exec.html
such error messages caused by list all sort of options
without any information when they where introduced are
really annoying - the docs should clearly say the minimum
required systemd version and the more options are added
the more important is that
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:10] Unknown lvalue 'RuntimeDirectory' in
section 'Service'
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:11] Unknown lvalue 'RuntimeDirectoryMode' in
section 'Service
Won't this be solved by using the man pages shipped with the version
of systemd you are using?
no - for several reasons

* it's more comfortable to use a website with working links like
http://www.freedesktop.org/software/systemd/man/systemd.kill.html
mentioned as example in ExecStop=

* it's more comfortable to have STRG+F in a webbrowsers

* i currently maintain machines with 204, 208 and 215
having *one* manual open which lists all available options
and mention the minimum version of them gives a better picture
Mauricio Tavares
2014-07-30 12:32:44 UTC
Permalink
's
Post by Reindl Harald
Post by Tom Gundersen
Post by Reindl Harald
http://www.freedesktop.org/software/systemd/man/systemd.exec.html
such error messages caused by list all sort of options
without any information when they where introduced are
really annoying - the docs should clearly say the minimum
required systemd version and the more options are added
the more important is that
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:10] Unknown lvalue 'RuntimeDirectory' in
section 'Service'
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:11] Unknown lvalue 'RuntimeDirectoryMode' in
section 'Service
Won't this be solved by using the man pages shipped with the version
of systemd you are using?
no - for several reasons
* it's more comfortable to use a website with working links like
http://www.freedesktop.org/software/systemd/man/systemd.kill.html
mentioned as example in ExecStop=
* it's more comfortable to have STRG+F in a webbrowsers
* i currently maintain machines with 204, 208 and 215
having *one* manual open which lists all available options
and mention the minimum version of them gives a better picture
Tom, I see no reason why having the man page indicate when a
given option was introduced be any worse than your suggestion. Since
the online man page better be the latest one, if it stated when each
option was introduced Reindl can use the online page as he wants and
those who want to use the man page in their computers can do the same.
Everyone wins.
Post by Reindl Harald
_______________________________________________
systemd-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/systemd-devel
Zbigniew Jędrzejewski-Szmek
2014-07-30 15:31:33 UTC
Permalink
Post by Mauricio Tavares
's
Post by Reindl Harald
Post by Tom Gundersen
Post by Reindl Harald
http://www.freedesktop.org/software/systemd/man/systemd.exec.html
such error messages caused by list all sort of options
without any information when they where introduced are
really annoying - the docs should clearly say the minimum
required systemd version and the more options are added
the more important is that
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:10] Unknown lvalue 'RuntimeDirectory' in
section 'Service'
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:11] Unknown lvalue 'RuntimeDirectoryMode' in
section 'Service
Won't this be solved by using the man pages shipped with the version
of systemd you are using?
no - for several reasons
* it's more comfortable to use a website with working links like
http://www.freedesktop.org/software/systemd/man/systemd.kill.html
mentioned as example in ExecStop=
* it's more comfortable to have STRG+F in a webbrowsers
* i currently maintain machines with 204, 208 and 215
having *one* manual open which lists all available options
and mention the minimum version of them gives a better picture
Tom, I see no reason why having the man page indicate when a
given option was introduced be any worse than your suggestion. Since
the online man page better be the latest one, if it stated when each
option was introduced Reindl can use the online page as he wants and
those who want to use the man page in their computers can do the same.
Everyone wins.
Some of our man pages in section 3 partially have history, see e.g. [1].
I think having such information is very useful, but keeping it accurate
is harder then it might seem at first. For example look at
SocketUser/SocketGroup settings. They were added in systemd-214, but
then were backported to 208-stable and 204-stable, and appeared in
Fedora in a 204 update has Fedora 19 has been out for more than an a
year [2]. It turns out that in this case man pages distributed with
the system are a more accurate source of information then anything
that could be included by upstream. So I'd be happy to merge patches
which judiciously add history for manpages which describe API changes
(i.e. section 3), but in general I don't think we have the man power
to fully describe full history of all settings in systemd.

Zbyszek

[1] http://www.freedesktop.org/software/systemd/man/sd_journal_open.html#History
[2] https://admin.fedoraproject.org/updates/FEDORA-2014-8761/systemd-204-20.fc19
Reindl Harald
2014-07-30 15:48:42 UTC
Permalink
Post by Zbigniew Jędrzejewski-Szmek
Some of our man pages in section 3 partially have history, see e.g. [1].
I think having such information is very useful, but keeping it accurate
is harder then it might seem at first. For example look at
SocketUser/SocketGroup settings. They were added in systemd-214, but
then were backported to 208-stable and 204-stable, and appeared in
Fedora in a 204 update has Fedora 19 has been out for more than an a
year [2]
the distribution backports don't matter in that context

the important information is "feature sounds cool, what
systemd version do i need at least" with that i know how
how my plans have do look like - grab if there is a backport
is a different story, users need to know "works on F20, F21
but not on F19 and RHEL7"

options introduced with 208 as example are considered for
my own rpm packages after the last machine is on F20 and
if "PrivateDevices" would be available on F20 i would even
give priority the F20 migration of our infrastructure
Post by Zbigniew Jędrzejewski-Szmek
It turns out that in this case man pages distributed with
the system are a more accurate source of information then anything
that could be included by upstream. So I'd be happy to merge patches
which judiciously add history for manpages which describe API changes
(i.e. section 3), but in general I don't think we have the man power
to fully describe full history of all settings in systemd
wrong way around - don't think that complicated
somebody wrote that text below, see my fixed version at the end

*now* it is a mess and likely nobody will be able to fix the past
*but* for new options "Introduced with systemd-XXX" would be a no-brainer
_____________________________________________

RuntimeDirectory=, RuntimeDirectoryMode=

Takes a list of directory names. If set, one or more directories by the specified names will be created below /run
(for system services) or below $XDG_RUNTIME_DIR (for user services) when the unit is started, and removed when the
unit is stopped. The directories will have the access mode specified in RuntimeDirectoryMode=, and will be owned by
the user and group specified in User= and Group=. Use this to manage one or more runtime directories of the unit
and bind their lifetime to the daemon runtime. The specified directory names must be relative, and may not include
a "/", i.e. must refer to simple directories to create or remove. This is particularly useful for unprivileged
daemons that cannot create runtime directories in /run due to lack of privileges, and to make sure the runtime
directory is cleaned up automatically after use. For runtime directories that require more complex or different
configuration or lifetime guarantees, please consider using tmpfiles.d(5). Introduced with systemd-214
Lennart Poettering
2014-08-04 15:10:58 UTC
Permalink
Post by Reindl Harald
* it's more comfortable to have STRG+F in a webbrowsers
"less" and similar pagers actually have search, simply by pressing
"/".

Lennart
--
Lennart Poettering, Red Hat
Dave Reisner
2014-07-30 14:16:53 UTC
Permalink
Post by Tom Gundersen
Post by Reindl Harald
http://www.freedesktop.org/software/systemd/man/systemd.exec.html
such error messages caused by list all sort of options
without any information when they where introduced are
really annoying - the docs should clearly say the minimum
required systemd version and the more options are added
the more important is that
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:10] Unknown lvalue 'RuntimeDirectory' in
section 'Service'
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:11] Unknown lvalue 'RuntimeDirectoryMode' in
section 'Service
Won't this be solved by using the man pages shipped with the version
of systemd you are using?
Sure, this works when you need to figure out if your current systemd
supports a directive. It doesn't work for the quasi-inverse question --
given a directive, what version of systemd do I need to support this?
For people who don't run the latest and greatest all the time, I can
understand why this might be valuable.

Maybe there's some way of using git history of the gperf files to
compile a systemd.availability manpage (similar to systemd.directives).

d
Lennart Poettering
2014-08-04 15:09:42 UTC
Permalink
Post by Reindl Harald
http://www.freedesktop.org/software/systemd/man/systemd.exec.html
such error messages caused by list all sort of options
without any information when they where introduced are
really annoying - the docs should clearly say the minimum
required systemd version and the more options are added
the more important is that
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:10] Unknown lvalue 'RuntimeDirectory' in
section 'Service'
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:11] Unknown lvalue 'RuntimeDirectoryMode' in
section 'Service
I am a bit conservative about doing this, since it would actually make
the man pages much larger if we want this to be comprehensive. Also, I
really don't want to litter the normal man pages with so much
information about possibly pre-historical versions of systemd. It
clutters the view, and makes people assume they would have to care for
the old versions all times. I mean, currently many of the pages shipped
with the "manpages" packages contain information about what feature is
supported in 1.x kernels or in glibc < 2, and stuff. And I really never
ever want to be in the business of listing such cruft.

What I'd be open to is if we keep this relatively isolated, strictly
automatically generated and with a cutoff point where all versions that
were released let's say 2y ago are subsumed under a single version. It
shouldn't be too hard to write a script that automatically generates
something like a minimal version of systemd.directives(7), that is
enriched with data from the git history or so, and simply says "Since
189" or so, for each of the configuration options.

Happy to take a clean patch for something like that.

Lennart
--
Lennart Poettering, Red Hat
Reindl Harald
2014-08-04 15:17:42 UTC
Permalink
Post by Lennart Poettering
Post by Reindl Harald
http://www.freedesktop.org/software/systemd/man/systemd.exec.html
such error messages caused by list all sort of options
without any information when they where introduced are
really annoying - the docs should clearly say the minimum
required systemd version and the more options are added
the more important is that
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:10] Unknown lvalue 'RuntimeDirectory' in
section 'Service'
Jul 30 13:17:09 rh systemd[1]: [/usr/lib/systemd/system/mysqld.service:11] Unknown lvalue 'RuntimeDirectoryMode' in
section 'Service
I am a bit conservative about doing this, since it would actually make
the man pages much larger if we want this to be comprehensive. Also, I
really don't want to litter the normal man pages with so much
information about possibly pre-historical versions of systemd. It
clutters the view, and makes people assume they would have to care for
the old versions all times. I mean, currently many of the pages shipped
with the "manpages" packages contain information about what feature is
supported in 1.x kernels or in glibc < 2, and stuff. And I really never
ever want to be in the business of listing such cruft.
What I'd be open to is if we keep this relatively isolated, strictly
automatically generated and with a cutoff point where all versions that
were released let's say 2y ago are subsumed under a single version. It
shouldn't be too hard to write a script that automatically generates
something like a minimal version of systemd.directives(7), that is
enriched with data from the git history or so, and simply says "Since
189" or so, for each of the configuration options.
Happy to take a clean patch for something like that
for Fedora 2 years would be fine to at least find the information
if it is in "old-stable", "stable" or Rawhide supported, for
users of long supported distributions maybe not

keep in mind systemd is now part of RHEL and Debian in the future

i don't get why it is "cruft" to add at the end of the description while
someone anyways needs to write it per hand " (introduced with systemd-215)"
Continue reading on narkive:
Loading...