[gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en/handbook: hb-working-rcscripts.xml

[gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en/handbook: hb-working-rcscripts.xml

[Sven Vermeulen (swift)]

swift       11/09/17 12:45:11

  Modified:             hb-working-rcscripts.xml
  Log:
  Bug #382373 - Use extra_commands instead of opts. Reported by Thomas Kahle

Revision  Changes    Path
1.36                 xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.36&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.36&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?r1=1.35&r2=1.36

Index: hb-working-rcscripts.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -r1.35 -r1.36
--- hb-working-rcscripts.xml	17 Aug 2011 07:57:23 -0000	1.35
+++ hb-working-rcscripts.xml	17 Sep 2011 12:45:11 -0000	1.36
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.35 2011/08/17 07:57:23 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.36 2011/09/17 12:45:11 swift Exp $ -->
 
 <sections>
 
@@ -14,8 +14,8 @@
 these aspects and explains how to deal with these scripts.
 </abstract>
 
-<version>4</version>
-<date>2011-08-17</date>
+<version>5</version>
+<date>2011-09-17</date>
 
 <section>
 <title>Runlevels</title>
@@ -719,13 +719,13 @@
 
 <p>
 If you want your init script to support more options than the ones we have
-already encountered, you should add the option to the <c>opts</c> variable, and
-create a function with the same name as the option. For instance, to support an
-option called <c>restartdelay</c>:
+already encountered, you should add the option to the <c>extra_commands</c>
+variable, and create a function with the same name as the option. For instance,
+to support an option called <c>restartdelay</c>:
 </p>
 
 <pre caption="Supporting the restartdelay option">
-opts="${opts} restartdelay"
+extra_commands="restartdelay"
 
 restartdelay() {
   stop

[gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en/handbook: hb-working-rcscripts.xml

[Sven Vermeulen (swift)]

swift       13/08/01 19:41:44

  Modified:             hb-working-rcscripts.xml
  Log:
  Fix bug #475924 - pause for initscripts no longer recommended, use --nodeps stop instead. thanks to Thomas D. for reporting.

Revision  Changes    Path
1.39                 xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.39&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.39&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?r1=1.38&r2=1.39

Index: hb-working-rcscripts.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -r1.38 -r1.39
--- hb-working-rcscripts.xml	31 Oct 2012 19:02:20 -0000	1.38
+++ hb-working-rcscripts.xml	1 Aug 2013 19:41:44 -0000	1.39
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.38 2012/10/31 19:02:20 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.39 2013/08/01 19:41:44 swift Exp $ -->
 
 <sections>
 
@@ -14,8 +14,8 @@
 these aspects and explains how to deal with these scripts.
 </abstract>
 
-<version>7</version>
-<date>2012-10-31</date>
+<version>8</version>
+<date>2013-08-01</date>
 
 <section>
 <title>Runlevels</title>
@@ -213,7 +213,7 @@
 <p>
 The scripts that the <c>rc</c> process starts are called <e>init scripts</e>.
 Each script in <path>/etc/init.d</path> can be executed with the arguments
-<e>start</e>, <e>stop</e>, <e>restart</e>, <e>pause</e>, <e>zap</e>,
+<e>start</e>, <e>stop</e>, <e>restart</e>, <e>zap</e>,
 <e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
 <e>broken</e>.
 </p>
@@ -235,15 +235,15 @@
 
 <p>
 If you want to stop a service, but not the services that depend on it, you can
-use the <c>pause</c> argument:
+use the <c>--nodeps</c> argument together with the <c>stop</c> command:
 </p>
 
 <pre caption="Stopping Postfix but keep the depending services running">
-# <i>/etc/init.d/postfix pause</i>
+# <i>/etc/init.d/postfix --nodeps stop</i>
 </pre>
 
 <p>
-If you want to see what status a service has (started, stopped, paused, ...) you
+If you want to see what status a service has (started, stopped, ...) you
 can use the <c>status</c> argument:
 </p>
 

[gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en/handbook: hb-working-rcscripts.xml

[Sven Vermeulen (swift)]

swift       12/10/31 19:02:21

  Modified:             hb-working-rcscripts.xml
  Log:
  Fix bug #431790 - Init scripts should be posix-sh, not bash

Revision  Changes    Path
1.38                 xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.38&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.38&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?r1=1.37&r2=1.38

Index: hb-working-rcscripts.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -r1.37 -r1.38
--- hb-working-rcscripts.xml	24 Jul 2012 12:12:52 -0000	1.37
+++ hb-working-rcscripts.xml	31 Oct 2012 19:02:20 -0000	1.38
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.37 2012/07/24 12:12:52 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.38 2012/10/31 19:02:20 swift Exp $ -->
 
 <sections>
 
@@ -14,8 +14,8 @@
 these aspects and explains how to deal with these scripts.
 </abstract>
 
-<version>6</version>
-<date>2012-07-24</date>
+<version>7</version>
+<date>2012-10-31</date>
 
 <section>
 <title>Runlevels</title>
@@ -703,12 +703,11 @@
 </pre>
 
 <p>
-Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
-free to use bash-compatible constructs inside your init script. However, you may
-want to write your init scripts to be POSIX-compliant. Future init script
-systems may allow symlinking <path>/bin/sh</path> to other shells besides
-bash.  Init scripts that rely on bash-only features will then break these
-configurations.
+Gentoo's init script syntax is based on the POSIX Shell so you are
+free to use sh-compatible constructs inside your init script. Keep other
+constructs, like bash-specific ones, out of the init scripts to ensure that the
+scripts remain functional regardless of the change Gentoo might do on its init
+system.
 </p>
 
 </body>

[gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en/handbook: hb-working-rcscripts.xml

[Sven Vermeulen (swift)]

swift       11/08/17 07:57:23

  Modified:             hb-working-rcscripts.xml
  Log:
  Part of bug #337140 - Improve description of use/need/before/after (or clarify it more since it was already documented)

Revision  Changes    Path
1.35                 xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.35&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.35&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?r1=1.34&r2=1.35

Index: hb-working-rcscripts.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -r1.34 -r1.35
--- hb-working-rcscripts.xml	14 Aug 2011 16:12:13 -0000	1.34
+++ hb-working-rcscripts.xml	17 Aug 2011 07:57:23 -0000	1.35
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.34 2011/08/14 16:12:13 swift Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.35 2011/08/17 07:57:23 swift Exp $ -->
 
 <sections>
 
@@ -14,8 +14,8 @@
 these aspects and explains how to deal with these scripts.
 </abstract>
 
-<version>3</version>
-<date>2011-08-12</date>
+<version>4</version>
+<date>2011-08-17</date>
 
 <section>
 <title>Runlevels</title>
@@ -454,10 +454,58 @@
 <body>
 
 <p>
-There are two dependencies you can define: <c>use</c> and <c>need</c>. As we
-have mentioned before, the <c>need</c> dependency is more strict than the
-<c>use</c> dependency. Following this dependency type you enter the service
-you depend on, or the <e>virtual</e> dependency.
+There are two dependency-alike settings you can define that influence the
+start-up or sequencing of init scripts: <c>use</c> and <c>need</c>. Next to
+these two, there are also two order-influencing methods called <c>before</c> and
+<c>after</c>. These last two are no dependencies per se - they do not make the
+original init script fail if the selected one isn't scheduled to start (or fails
+to start).
+</p>
+
+<ul>
+  <li>
+    The <c>use</c> settings informs the init system that this script <e>uses</e>
+    functionality offered by the selected script, but does not directly depend
+    on it. A good example would be <c>use logger</c> or <c>use dns</c>. If those
+    services are available, they will be put in good use, but if you do not have
+    a logger or DNS server the services will still work. If the services exist,
+    then they are started before the script that <c>use</c>'s them.
+  </li>
+  <li>
+    The <c>need</c> setting is a hard dependency. It means that the script that
+    is <c>need</c>'ing another script will not start before the other script is
+    launched successfully. Also, if that other script is restarted, then this
+    one will be restarted as well.
+  </li>
+  <li>
+    When using <c>before</c>, then the given script is launched before the
+    selected one <e>if</e> the selected one is part of the init level. So an
+    init script <path>xdm</path> that defines <c>before alsasound</c> will start
+    before the <path>alsasound</path> script, but only if <path>alsasound</path>
+    is scheduled to start as well in the same init level. If
+    <path>alsasound</path> is not scheduled to start too, then this particular
+    setting has no effect and <path>xdm</path> will be started when the init
+    system deems it most appropriate.
+  </li>
+  <li>
+    Similarly, <c>after</c> informs the init system that the given script should
+    be launched after the selected one <e>if</e> the selected one is part of the
+    init level. If not, then the setting has no effect and the script will be
+    launched by the init system when it deems it most appropriate.
+  </li>
+</ul>
+
+<p>
+It should be clear from the above that <c>need</c> is the only "true" dependency
+setting as it affects if the script will be started or not. All the others are
+merely pointers towards the init system to clarify in which order scripts can be
+(or should be) launched.
+</p>
+
+<p>
+Now, if you look at many of Gentoo's available init scripts, you will notice
+that some have dependencies on things that are no init scripts. These "things"
+we call <e>virtuals</e>.
 </p>
 
 <p>
@@ -511,16 +559,12 @@
 <body>
 
 <p>
-In some cases you might not require a service, but want your service to be
-started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
-available on the system (note the conditional - this is no dependency anymore)
-<e>and</e> run in the same runlevel (note the conditional - only services in the
-same runlevel are involved). You can provide this information using the 
-<c>before</c> or <c>after</c> settings.
-</p>
-
-<p>
-As an example we view the settings of the Portmap service:
+As we described in the previous section, you can tell the init system what order
+it should use for starting (or stopping) scripts. This ordering is handled both
+through the dependency settings <c>use</c> and <c>need</c>, but also through the
+order settings <c>before</c> and <c>after</c>. As we have described these
+earlier already, let's take a look at the Portmap service as an example of such
+init script.
 </p>
 
 <pre caption="The depend() function in the Portmap service">

[gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en/handbook: hb-working-rcscripts.xml

[Sven Vermeulen (swift)]

swift       11/08/12 19:34:56

  Modified:             hb-working-rcscripts.xml
  Log:
  Fix #348724 (documentation part) - Document that restart functionality is not something users can define in the init scripts themselves

Revision  Changes    Path
1.33                 xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.33&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.33&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?r1=1.32&r2=1.33

Index: hb-working-rcscripts.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -r1.32 -r1.33
--- hb-working-rcscripts.xml	2 Mar 2011 08:09:48 -0000	1.32
+++ hb-working-rcscripts.xml	12 Aug 2011 19:34:56 -0000	1.33
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.32 2011/03/02 08:09:48 nightmorph Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.33 2011/08/12 19:34:56 swift Exp $ -->
 
 <sections>
 
@@ -14,8 +14,8 @@
 these aspects and explains how to deal with these scripts.
 </abstract>
 
-<version>2</version>
-<date>2011-03-02</date>
+<version>3</version>
+<date>2011-08-12</date>
 
 <section>
 <title>Runlevels</title>
@@ -440,10 +440,6 @@
 stop() {
   <comment>(Commands necessary to stop the service)</comment>
 }
-
-restart() {
-  <comment>(Commands necessary to restart the service)</comment>
-}
 </pre>
 
 <p>
@@ -574,6 +570,11 @@
 
 <pre caption="Example start() function">
 start() {
+  if [ "${RC_CMD}" = "restart" ];
+  then
+    <comment># Do something in case a restart requires more than stop, start</comment>
+  fi
+
   ebegin "Starting my_service"
   start-stop-daemon --start --exec /path/to/my_service \
     --pidfile /path/to/my_pidfile
@@ -591,6 +592,15 @@
 service fails to start.
 </p>
 
+<p>
+Another notable setting used in the above example is to check the contents of
+the <c>RC_CMD</c> variable. Unlike the previous init script system, the newer
+<c>openrc</c> system does not support script-specific restart functionality.
+Instead, the script needs to check the contents of the <c>RC_CMD</c> variable
+to see if a function (be it <c>start()</c> or <c>stop()</c>) is called as part
+of a restart or not.
+</p>
+
 <note>
 Make sure that <c>--exec</c> actually calls a service and not just a shell
 script that launches services and exits -- that's what the init script is
@@ -604,14 +614,13 @@
 </p>
 
 <p>
-Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
-not obliged to define these functions! Our init system is intelligent enough to
-fill these functions by itself if you use <c>start-stop-daemon</c>.
+Another function you can define is <c>stop()</c>. You are not obliged to define
+this function though! Our init system is intelligent enough to fill in this
+function by itself if you use <c>start-stop-daemon</c>.
 </p>
 
 <p>
-Although you do not <e>have</e> to create a <c>stop()</c> function, here is an
-example:
+Here is an example of a <c>stop()</c> function:
 </p>
 
 <pre caption="Example stop() function">
@@ -681,6 +690,10 @@
 }
 </pre>
 
+<impo>
+The function <c>restart()</c> cannot be overridden in openrc!
+</impo>
+
 </body>
 </subsection>
 <subsection>

[gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en/handbook: hb-working-rcscripts.xml

[Joshua Saddler (nightmorph)]

nightmorph    11/03/02 08:09:48

  Modified:             hb-working-rcscripts.xml
  Log:
  add suggestion on posix-compliance for initscripts, bug 353979

Revision  Changes    Path
1.32                 xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.32&view=markup
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?rev=1.32&content-type=text/plain
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml?r1=1.31&r2=1.32

Index: hb-working-rcscripts.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- hb-working-rcscripts.xml	11 Oct 2007 20:09:02 -0000	1.31
+++ hb-working-rcscripts.xml	2 Mar 2011 08:09:48 -0000	1.32
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.31 2007/10/11 20:09:02 nightmorph Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.32 2011/03/02 08:09:48 nightmorph Exp $ -->
 
 <sections>
 
@@ -14,8 +14,8 @@
 these aspects and explains how to deal with these scripts.
 </abstract>
 
-<version>1.25</version>
-<date>2007-10-11</date>
+<version>2</version>
+<date>2011-03-02</date>
 
 <section>
 <title>Runlevels</title>
@@ -651,7 +651,11 @@
 
 <p>
 Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
-free to use bash-compatible constructs inside your init script.
+free to use bash-compatible constructs inside your init script. However, you may
+want to write your init scripts to be POSIX-compliant. Future init script
+systems may allow symlinking <path>/bin/sh</path> to other shells besides
+bash.  Init scripts that rely on bash-only features will then break these
+configurations.
 </p>
 
 </body>