[Initng-svn] r1971 - initng/doc
svn at initng.thinktux.net
svn at initng.thinktux.net
Mon Nov 7 11:40:14 CET 2005
Author: jimmy
Date: Mon Nov 7 11:40:13 2005
New Revision: 1971
Modified:
initng/doc/imanual.txt
Log:
New imanual written by Thomas Ilnseher
Modified: initng/doc/imanual.txt
==============================================================================
--- initng/doc/imanual.txt (original)
+++ initng/doc/imanual.txt Mon Nov 7 11:40:13 2005
@@ -13,179 +13,195 @@
Notice: the file must end in .i or initng will not see it!
Basic Syntax:
+# start SaTaN0rX
-Notice: The '=' is optional in all of the commands I list below, I added it because I think it looks cleaner but you can choose to use it or not as you see fit.
+there are different things: daemons and services.
-Naming the script (in the script).
+a service is something that is only run once and then terminates. examples
+are: mount something, set the hostname, bring the network up, ...
-Naming the service and doing the first required thing. The name of a service is the subfolder (not including /etc/initng) then the name of the program.
+in contrary, a daemon is a programm thats being started and runs all the time.
+for example apache, cups, ...
-Syntax:
+the first thing you need to do is to figure out what you want to write:
+an .i file for a service or a daemon?
-folder/name
+SERVICES:
-Example:
+a service might look like this:
-system/alsasound
-
-The first line of code (always):
-
-service folder/name {
-
-Warning: Do not forget the { there it is very very very important!
-
-Dependencies:
-
-A dependency is something the program or service depends upon to execute properly.
-
-Syntax:
-
-need = "folder/nameofdependency" "folder/nameofdependency"
-
-Example:
-
-need = "system/initial" "system/modules"
-
-Use:
-
-If a service is in this runlevel it waits on it to finish.
-
-Syntax:
-
-use = folder/name
-
-Example:
-
-use = system/static-modules
-
-Changing the directory:
-
-The following command allows you to change the directory you are working in.
-
-Syntax:
-
-chdir = /path/to/dir
-
-Example:
-
-chdir = /root/initng
-
-Chrooting:
-
-This lets you change the root when running a command.
-
-Syntax:
-
-chroot = /path/to/dir
-
-Example:
-
-chroot = /root/initng
-
-Delaying the start of a service/daemon:
-
-There are two ways to delay the start of a daemon or service. The first argument called "delay" takes a number in seconds. The other way is "udelay" which takes an argument in microseconds.
-
-Syntax:
-
-delay = time //seconds
-udelay = time //microseconds
-
-Example:
-
-delay = 10
-udelay = 10
-
-Running a service/daemon as another user:
-
-In most cases running a service/daemon as the root user is stupid and dangerous. So to solve this inherent security risk initng allows you to run the service/daemon as another user.
-
-Syntax:
-
-setuid = username
-
-Example:
-
-setuid = jimmy
-
-Setting a priority for a service/daemon:
-
-Some things that are executed are less important or more important than others.
-
-Syntax:
-
-nice = number //must be an integer as in no decimal point
-
-Example:
-
-nice = 19
-
-Starting a service:
-
-To start a service you use the start command or function.
-
-Syntax:
-
-start = /path/to/executable
+service system/foo {
+ need = system/initial system/mountfs
+ use = system/alsasound
+ start = /sbin/foo
+ start_args = bar baz
+}
-or
+i'll explain these lines.
+the first line says that this service requires system/initial and
+system/mountfs to be run before it can be started.
+
+the second line says that it should also wait for system/alsasound is also in
+the current runlevel, then it should also wait for system/alsasound. but if
+system/alsasound is NOT in the current runlevel, this line would be ignored.
+in contrary, if it would have said need = system/alsasound, then
+system/alsasound would also have been started even if it is not in the current
+runlevel.
+
+the third line gives the program to start, in this case /sbin/foo
+
+and the forth line, you may have guessed it, gives additional parameters that
+should be passed to /sbin/foo.
+
+ok, now can also have a service that does something on start and on shutdown.
+it would look like this:
+
+service system/foo {
+ need = system/initial system/mountfs
+ use = system/alsasound
+ start = /sbin/foo
+ start_args = bar baz
+ stop = /sbin/foo
+ stop_args = qux quux
+}
-start{ /path/to/executable }
+here, the stop and stop_args lines have been added. pretty easy.
+but there are situations in which you can not use some simple program, but u
+need a shell script. one solution would be to write that shell script to a
+file, and have a line like "start = /path/to/my/script.sh". while i would
+suggest you to do that for really large scripts (>100 lines), it would be kind
+an overkill to do so for a script with 5 lines of code. so initng provides a
+possibility to include these scripts .i files. example:
+
+service system/foo {
+ need = system/initial system/mountfs
+ use = system/alsasound
+ start {
+ [ -f /etc/conf.d/foo.conf ] && source /etc/conf.d/foo.conf
+ [ -z "$FOO" ] & FOO="bar baz"
+ /sbin/foo $FOO
+ }
+}
-Example:
+note that you could also have stop script-block that is executed on shutdown.
-start = /opt/foldingathome/client1/foldingathome
+DAEMONS:
-or
+a basic daemon .i file might look like this:
+daemon daemon/vixie-cron {
+ need = system/initial system/clock system/mountfs system/bootmisc
+ daemon = /usr/sbin/cron
+ daemon_args = -n
+}
-start{ /opt/foldingathome/client1/foldingathome }
+it starts with "daemon daemon/blah {", and has a daemon = line in it.
+the "daemon =" specifies the daemon executable.
-Passing arguments to a service before starting it:
+a daemon doesn't have start, start_args, stop, stop_args directives, but has a
+daemon and daemon_args directive. all other directives are the same then with
+services.
+
+initng will by default track what the daemons are doing, ie it will monitor if
+a daemon crashes, etc. unfotunately, some daemons have a bad habit: forking.
+
+when a daemon forks, it spawns a copy of itself with a new pid. then the
+father process, with the old pid, dies.
+
+this has some advantages: if you start cron from your console, then you
+instantly will see the bash prompt again. thats why most daemons fork.
+
+unfortunately, initng has up to now no possibility to know if a daemon spawns
+a child or not. initng will only notice that the father process dies, and
+thinks that the daemon died.
+
+fortunately most daemons have a commandline switch which makes them not
+forking. in the case of vixie-cron it is -n. consult your daemons manpage.
+
+in some cases, the daemon can't be prevented from forking, but it will write
+the pid of the child process in a file, called the pid-file. initng can also use
+the pid file to track the daemon. an example:
+
+daemon daemon/ntpd {
+ need = system/initial system/mountfs system/mountfs net/lo
+ require_network
+ use = daemon/ntpdate
+ daemon = /usr/sbin/ntpd
+ daemon_args = -p /var/run/ntpd.pid
+ pid_file = /var/run/ntpd.pid
+}
-This is where you would put the options you pass your programs.
-Syntax:
+this daemon WILL fork, but it will write the pid of the doughter process in
+/var/run/ntpd.pid. initng can also track this daemon.
-start_args = args
+another thing you can see is the require_network directive. this will delay
+the starting of this daemon until a network device is set up.
-Example:
+ok, what's the buzz when you need some shell script to bring up the daemon?
+have a look at this example:
-start_args = -k
+daemon daemon/acpid {
+ need = system/mountfs system/modules
+ use = system/discover system/coldplug
+ daemon {
-To stop a service you use the stop command or function.
-Syntax:
+ # As the name says. If the kernel supports modules, it'll try to load
+ # the ones listed in "MODULES".
+
+ .....
+ # Check for ACPI support on kernel side
+ [ -d /proc/acpi ] || exit 0
-stop = /path/to/executable
+ # Include acpid defaults if available
+ OPTIONS=""
+ if [ -f /etc/default/acpid ] ; then
+ . /etc/default/acpid
+ fi
-Example:
+ [ -f /proc/modules ] && load_modules
-stop = /opt/foldingathome/client1/foldingathome
-Passing arguments to a service when stopping it:
+ #for x in ac battery button fan ibm_acpi processor thermal video ; do
+ # modprobe ${x} &> /dev/null
+ #done
-This is where the options to stop the program that you want to stop go
+ exec /usr/sbin/acpid -f -c /etc/acpi/events
+ }
+}
-Syntax:
+i've shortened this a little bit :P
-start_args = args
+as you can see you can also embedd an "daemon { script }" bash script in an .i
+file. but notice the "exec blah" statement. when you write "exec blah" in an
+bash script, the blah process will REPLACE the bash process, inheriting it's
+pid. this is necessary, so that initng can track your service. if you use
+pid_file, it is not absolutely necessary, but i'd suggest to do so.
-Example:
+note that if you have a daemon that neither could be prevented from forking,
+nor does export a pidfile, you can write a shell script that figures out the
+pid of your daemon with ps + [awk|sed|cut] and writes the pidfile. in this
+case you must not use exec, cause exec will kill the bash, so your script will
+stop at the exec statement.
-start_args = -P
+NAMING THE .i FILE:
+when you name the .i file:
+initng will look for the service "daemon/something" in
+"/etc/initng/daemon/smoething.i". so the exaple above has to go into
+"/etc/initng/daemon/acpid.i".
-To finish the .i file you are writing:
+DIRECTIVES:
+this should give an incomplete list of the other directives not explained
+above.
-Simply put a } at the bottom of the file to finish up
+require_network: the start service or daemon is delayed until a network device
+ other then lo is configured.
-Example .i file:
+last: the start service or daemon is delayed until all services and daemons,
+ which are not last, are started.
-service net/firestarter {
-need = net/eth0
+respawn: if the daemon dies, it will be restarted.
-start = /usr/bin/firestarter
-stop = /usr/bin/firestarter
+many others...
-start_args = -s
-stop_args = -p
-}
+To be continued ...
More information about the Initng-svn
mailing list